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Read This First 


About This Manual 


The TMS320C3x/C4x Optimizing C Compiler User’s Guide tells you how to 
use these compiler tools: 

□ Compiler 

□ Source interlist utility 

□ Optimizer 

□ Preprocessor 

□ Library-build utility 

This compiler accepts American National Standards Institute (ANSI) standard 
C source code and produces assembly language source code for the 
TMS320C3x/4x devices. 

This user’s guide discusses the characteristics of the TMS320C3x/4x opti¬ 
mizing C compiler. It assumes that you already know how to write C programs. 
The C Programming Language (second edition), by Brian W. Kernighan and 
Dennis M. Ritchie, describes C based on the ANSI C standard. Use the 
Kernighan and Ritchie book as a supplement to this manual. 

Before you can use this book, you should read the TMS320C3x/C4x Code 
Generation Tools Getting Started Guide to install the C compiler tools. 



How to Use This Manual / Notational Conventions 


How to Use This Manual 

The goal of this book is to help you learn how to use the Texas Instruments C 
compiler tools specifically designed for the TMS320C3x/4x devices. This 
book is divided into three distinct parts: 

□ Introductory information, in chapter one, provides an overview of the 
TMS320C3x/4x development tools. 

□ Compiler description, in chapter two, describes how to operate the C 
compiler and the shell program, and discusses specific characteristics of 
the C compiler as they relate to the ANSI C specification. It contains tech¬ 
nical information on the TMS320C3x/4x architecture and includes 
information needed for interfacing assembly language to C programs. It 
describes libraries and header files in addition to the macros, functions, 
and types they declare. Finally, it describes the library-build utility. 

□ Reference material, in chapters three through six and the glossary, pro¬ 
vides supplementary information on TMS320C3x/4x specific optimiza¬ 
tions, and definitions of terms used in the book. 


Notational Conventions 

This document uses the following conventions. 

□ Program listings, program examples, and interactive displays are shown 
in a special typeface similar to a typewriter’s. Examples use a bold 
version of the special typeface for emphasis; interactive displays use a 
bold version of the special typeface to distinguish commands that you 
enter from items that the system displays (such as prompts, command 
output, error messages, etc.). 

Here is a sample program listing: 


0011 

0005 

0001 

.field 

1 , 

2 

0012 

0005 

0003 

. field 

3, 

4 

0013 

0005 

0006 

.field 

6, 

3 

0014 

0006 


. even 




Here is an example of a system prompt and a command that you might 
enter: 

C: csr -a /user/ti/simuboard/utilities 

□ In syntax descriptions, the instruction, command, or directive is in a bold 
typeface font and parameters are in an italic typeface. Portions of a syntax 
that are in bold should be entered as shown; portions of a syntax that are 
in italics describe the type of information that should be entered. Here is 
an example of a directive syntax: 


iv 


Notational Conventions 


.asect "section name”, address 

.asect is the directive. This directive has two parameters, indicated by sec¬ 
tion name and address. When you use .asect, the first parameter must be 
an actual section name, enclosed in double quotes; the second parameter 
must be an address. 

□ Square brackets ([ and ]) identify an optional parameter. If you use an 
optional parameter, you specify the information within the brackets; you 
don’t enter the brackets themselves. Here’s an example of an instruction 
that has an optional parameter: 

LALK 16-bit constant [, shift] 

The LALK instruction has two parameters. The first parameter, 16-bit con¬ 
stant, is required. The second parameter, shift, is optional. As this syntax 
shows, if you use the optional second parameter, you must precede it with 
a comma. 

Square brackets are also used as part of the pathname specification for 
VMS pathnames; in this case, the brackets are actually part of the path¬ 
name (they are not optional). 

□ Braces ( {and} ) indicate a list. The symbol | (read as or) separates items 
within the list. Here’s an example of a list: 

{*!*+!*-} 

This provides three choices: *, *+, or 

Unless the list is enclosed in square brackets, you must choose one item 
from the list. 

□ Some directives can have a varying number of parameters. For example, 
the .byte directive can have up to 100 parameters. The syntax for this di¬ 
rective is: 

.byte value-i [,..., value n ] 

This syntax shows that .byte must have at least one value parameter, but 
you have the option of supplying additional value parameters, separated 
by commas. 
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Related Documentation From Texas Instruments 

The following books describe the TMS320C3x/C4x and related support tools. 

To obtain a copy of any of these Tl documents, call the Texas Instruments Liter¬ 
ature Response Center at (800) 477-8924. When ordering, please identify the 

book by its title and literature number. 

TMS320C3x/C4x Code Generation Tools Getting Started Guide (literature 
number SPRU119) describes how to install the TMS320C3x/C4x 
assembly language tools and the C compiler. Installation instructions are 
included for MS-DOS™, Windows™ 3.x, Windows NT, Windows 95, 
SunOS™, Solaris, and HP-UX™ systems. 

TMS320C3x/C4x Assembly Language Tools User’s Guide (literature 
number SPRU035) describes the assembly language tools (assembler, 
linker, and other tools used to develop assembly language code), 
assembler directives, macros, common object file format, and symbolic 
debugging directives for the ’C3x and ’C4x generations of devices. 

TMS320C3x C Source Debugger User’s Guide (literature number 
SPRU053) tells you howto invoke the ’C3x emulator, evaluation module, 
and simulator versions of the C source debugger interface. This book 
discusses various aspects of the debugger interface, including window 
management, command entry, code execution, data management, and 
breakpoints. It also includes a tutorial that introduces basic debugger 
functionality. 

TMS320C4x C Source Debugger User’s Guide (literature number 
SPRU054) tells you how to invoke the ’C4x emulator and simulator ver¬ 
sions of the C source debugger interface. This book discusses various 
aspects of the debugger interface, including window management, com¬ 
mand entry, code execution, data management, and breakpoints. It also 
includes a tutorial that introduces basic debugger functionality. 

TMS320C3x User’s Guide (literature number SPRU031) describes the ’C3x 
32-bit floating-point microprocessor (developed for digital signal proces¬ 
sing as well as general applications), its architecture, internal register 
structure, instruction set, pipeline, specifications, and DMA and serial 
port operation. Software and hardware applications are included. 

TMS320C32 Addendum to the TMS320C3x User’s Guide (literature num¬ 
ber SPRU132) describes the TMS320C32 floating-point microprocessor 
(developed for digital signal processing as well as general applications). 
Discusses its architecture, internal register structure, specifications, and 
DMA and serial port operation. Hardware applications are also included. 
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Related Documentation From Texas Instruments 


TMS320C4x User’s Guide (literature number SPRU063) describes the ’C4x 
32-bit floating-point processor, developed for digital signal processing as 
well as parallel processing applications. Covered are its architecture, in¬ 
ternal register structure, instruction set, pipeline, specifications, and op¬ 
eration of its six DMA channels and six communication ports. 

Parallel Processing with the TMS320C4x (literature number SPRA031) de¬ 
scribes parallel processing and how the ’C4x can be used in parallel pro¬ 
cessing. Also provides sample parallel processing applications. 

TMS320C4x General-Purpose Applications User’s Guide (literature 
number SPRU159) describes software and hardware applications for 
the ’C4x processor. Also includes development support information, 
parts lists, and XDS510 emulator design considerations. 

TMS320C30 Evaluation Module Technical Reference (literature number 
SPRU069) describes board-level operation of the TMS320C30 evalua¬ 
tion module. 

Digital Signal Processing Applications With the TMS320C30 Evaluation 
Module Selected Application Notes (literature number SPRA021) 
contains useful information for people who are preparing and debugging 
code. The book gives additional information about the TMS320C30 eval¬ 
uation module, as well as C coding tips. 

TMS320 DSP Development Support Reference Guide (literature number 
SPRU011) describes the TMS320 family of digital signal processors and 
the tools that support these devices. Included are code-generation tools 
(compilers, assemblers, linkers, etc.) and system integration and debug 
tools (simulators, emulators, evaluation modules, etc.). Also covered are 
available documentation, seminars, the university program, and factory 
repair and exchange. 

TMS320 DSP Designer’s Notebook: Volume 1 (literature number 
SPRT125) presents solutions to common design problems using ’C2x, 
’C3x, ’C4x, ’C5x, and other Tl DSPs. 

TMS320 Third-Party Support Reference Guide (literature number 
SPRU052) alphabetically lists over 100 third parties that provide various 
products that serve the family of TMS320 digital signal processors. A 
myriad of products and applications are offered—software and hardware 
development tools, speech recognition, image processing, noise can¬ 
cellation, modems, etc. 


Read This First 
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Related Documentation / Trademarks 


Related Documentation 

The CProgramming Language (second edition), by Brian W. Kernighan and 
Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New 
Jersey, 1988, describes ANSI C. You can use it as a reference. 

You may find these documents helpful as well: 

Advanced C: Techniques and Applications, Sobelman, Gerald E., and 
David E. Krekelberg, Que Corporation 

American National Standards Institute C Specification, American National 
Standard for Information Systems—Programming Language C 
x3.159-1989 (ANSI standard for C) 

Programming in C, Kochan, Steve G., Hayden Book Company 

Understanding and Using COFF, Gircys, Gintaras R., published by O’Reilly 
and Associates, Inc 


Trademarks 

HP-UX is a trademark of Hewlett-Packard Company. 

MS-DOS is a registered trademark of Microsoft Corporation. 

PC-DOS is a trademark of International Business Machines Corporation. 
Solaris is a trademark of Sun Microsystems, Inc. 

SunOS is a trademark of Sun Microsystems, Inc. 

UNIX is a registered trademark in the United States and other countries, 
licensed exclusively through X/Open Company Limited. 

XDS is a trademark of Texas Instruments Incorporated. 
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If You Need Assistance 


If You Need Assistance... 


□ World-Wide Web Sites 

Tl Online 

Semiconductor Product Information Center (PIC) 

DSP Solutions 

320 Hotline On-line™ 


http://www.ti.com 

http://www.ti.com/sc/docs/pic/home.htm 

http://www.ti.com/dsps 

http //www. ti. com/sc/docs/dsps/su pport. htm 


□ North America, South America, Central America 

Product Information Center (PIC) (972) 644-5580 

Tl Literature Response Center U.S.A. (800) 477-8924 

Software Registration/Upgrades (214)638-0333 Fax: (214)638-7742 

U.S.A. Factory Repair/Hardware Upgrades (281) 274-2285 

U.S. Technical Training Organization (972) 644-5580 

DSP Hotline (281)274-2320 Fax: (281)274-2324 

DSP Modem BBS (281) 274-2323 

DSP Internet BBS via anonymous ftp to ftp://ftp.ti.com/pub/tms320bbs 


Email: dsph@ti.com 


□ Europe, Middle East, Africa 


European Product Information Center (EPIC) Hotlines: 


Multi-Language Support 

+33 1 

30 

70 

11 

69 

Email: epic@ti.com 






Deutsch +49 8161 80 33 11 

or +33 1 

30 

70 

11 

68 

English 

+33 1 

30 

70 

11 

65 

Francais 

+33 1 

30 

70 

11 

64 

Italiano 

+33 1 

30 

70 

11 

67 

EPIC Modem BBS 

+33 1 

30 

70 

11 

99 

European Factory Repair 

+33 4 

93 

22 

25 

40 

Europe Customer Training Helpline 







Fax: +33 1 30 70 10 32 


Fax: +49 81 61 80 40 10 


□ Asia-Pacific 


Literature Response Center 
Hong Kong DSP Hotline 
Korea DSP Hotline 
Korea DSP Modem BBS 


+852 2 956 7288 
+852 2 956 7268 
+82 2 551 2804 
+82 2 551 2914 


Fax: +852 2 956 2200 
Fax: +852 2 956 1002 
Fax: +82 2 551 2828 


Singapore DSP Hotline 
Taiwan DSP Hotline 
Taiwan DSP Modem BBS 


Fax: +65 390 7179 

+886 2 377 1450 Fax: +886 2 377 2718 
+886 2 376 2592 


Taiwan DSP Internet BBS via anonymous ftp to ftp://dsp.ee.tit.edu.tw/pub/TI/ 


□ Japan 

Product Information Center +0120-81-0026 (in Japan) 

+03-3457-0972 or (INTL) 813-3457-0972 
DSP Hotline +03-3769-8735 or (INTL) 813-3769-8735 

DSP BBS via Nifty-Serve Type “Go TIASP” 


Fax: +0120-81-0036 (in Japan) 

Fax: +03-3457-1259 or (INTL) 813-3457-1259 
Fax: +03-3457-7071 or (INTL) 813-3457-7071 


□ Documentation 

When making suggestions or reporting errors in documentation, please include the following information that is on the title 
page: the full title of the book, the publication date, and the literature number. 

Mail: Texas Instruments Incorporated Email: dsph@ti.com 

Technical Documentation Services, MS 702 
P.O. Box 1443 

Houston, Texas 77251-1443 


Note: When calling a Literature Response Center to order documentation, please specify the literature number of the 
book. 
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Chapter 1 


Introduction 


The TMS320 family of digital signal processors (DSPs) combines the high 
performance required in DSP applications with special features for these 
applications. 

The TMS320C3x/C4x DSPs are fully supported by a complete set of code 
generation tools including an optimizing C compiler, an assembler, a linker, 
an archiver, a software simulator, a full-speed emulator, and a software 
development board. 

This chapter provides an overview of these tools and introduces the features 
of the optimizing C compiler. The assembler and linker are discussed in detail 
in the TMS320C3x/C4x Assembly Language Tools User’s Guide. 
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Page 


1.1 Software Development Tools Overview 

1.2 TMS320C3x/C4x C Compiler Overview 
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1.1 Software Development Tools Overview 

Figure 1-1 illustrates the TMS320C3x/C4x software development flow. The 
shaded portion of the figure highlights the most common path of software 
development; the other portions are optional. 

Figure 1-1. TMS320C3x/C4x Software Development Flow 
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Software Development Tools Overview 


The following list describes the tools that are shown in Figure 1-1: 

□ The C compiler accepts C source code and produces TMS320C3x or 
TMS320C4x assembly language source code. A shell program (cl30), 
an optimizer (opt30), and an interlist utility (clist) are included in the 
compiler package. 

■ The shell program enables you to automatically compile, assemble, 
and link source modules. 

■ The optimizer modifies code to improve the efficiency of C programs. 

■ The interlist utility interlists C source statements with assembly lan¬ 
guage output. 

Chapter 2 describes how to invoke and operate the compiler, the shell, the 
optimizer, and the interlist utility. 

□ The assembler translates assembly language source files into machine 
language object files. The machine language is based on common object 
file format (COFF). The TMS320C3x/C4x Assembly Language Tools 
User’s Guide explains how to use the assembler. 

□ The linker (Ink30) combines object files into a single executable object 
module. As it creates the executable module, it performs relocation and 
resolves external references. The linker accepts relocatable COFF object 
files and object libraries as input. 

□ The archiver (ar30) allows you to collect a group of files into a single 
archive file, called a library. It also allows you to modify a library by 
deleting, replacing, extracting, or adding members. One of the most useful 
applications of the archiver is building a library of object modules. 

□ Eight object libraries are shipped with the C compiler. These libraries 
contain ANSI-standard runtime support functions and compiler-utility 
functions for the TMS320C3x and TMS320C4x. See Section 2.3 for a de¬ 
scription of these libraries. 

□ Use the library-build utility (mk30), to build your own customized 
runtime-support library. Standard runtime-support library functions are 
provided as source code. 

■ rts.src contains standard runtime functions for the TMS320C3x/C4x 
processors. 

■ mathasm.src contains assembly language source for trigonometric 
functions 

■ prts30.src contains C and assembly language routines for handling 
peripherals/interrupts for ’C3x devices 
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■ prts40.src contains C and assembly language routines for handling 
peripherals and interrupts for ’C4x devices 

□ The hex conversion utility (hex30) converts a COFF object file into 
ASCII-hex, Intel, Motorola-S, Tl-Tagged, or Tektronix object format. The 
converted file can be downloaded to an EPROM programmer. The 
TMS320C3x/C4x Assembly Language Tools User's Guide explains how 
to use the hex conversion utility. 

The main purpose of this development process is to produce a module that can 
be executed in a TMS320C3x/C4x target system. You can use one of several 
debugging tools to refine and correct your code before downloading it to a 
TMS320C3x/C4x target system. These debugging platforms share a common 
screen-oriented interface that allows you to display machine status informa¬ 
tion, inspect and modify C variables, display C source code, and monitor the 
execution of your program as it runs on the debugging platform. Available de¬ 
bugging tools include: 

□ An instruction-accurate software simulator that simulates the 
TMS320C3x/C4x functions. The simulator executes linked COFF object 
modules. 

□ An XDS (extended development system) emulator, which is a PC- 
resident, real-time, in-circuit emulator that features the same screen-ori¬ 
ented interface as the simulator 

□ An EVM (evaluation module), which is a plug-in PC board that contains 
a target CPU, such as a C30, that can be used to evaluate CPU 
performance 


1-4 


TMS320C3x/C4x C Compiler Overview 


1.2 TMS320C3x/C4x C Compiler Overview 

The TMS320C3x/C4x C compiler is a full-featured optimizing compiler that 
translates standard ANSI C programs into TMS320C3x/C4x assembly 
language source. The following list describes key features of the compiler: 

ANSI Standard C 

The TMS320C3x/C4x compiler fully conforms to the ANSI C standard as de¬ 
fined by the ANSI specification and described in Kernighan and Ritchie’s The 
C Programming Language (second edition). The ANSI standard includes 
recent extensions to C that are now standard features of the language. These 
extensions provide maximum portability and increased capability. 

Optimization 

The compiler uses a sophisticated optimization pass that employs several 
advanced techniques for generating efficient, compact code from C source. 
General optimizations can be applied to any C code, and 
TMS320C3x/C4x-specific optimizations take advantage of the particular 
features of the TMS320C3x/C4x architecture. For more information about the 
C compiler’s optimization techniques, refer to Section 2.4 on page 2-38 and 
to Appendix A. 

ANSI Standard Runtime Support 

The compiler package comes with eight complete runtime libraries. All library 
functions conform to the ANSI C library standard. The libraries include 
functions for string manipulation, dynamic memory allocation, data conver¬ 
sion, timekeeping, and trigonometry, plus exponential and hyperbolic 
functions. Functions for I/O and signal handling are not included, because 
these are target-system specific. For more information, refer to Chapter 5. 

Assembly Source Output 

The compiler generates assembly language source that is easily inspected, 
enabling you to see the code generated from the C source files. 

Big and Small Memory Models 

The compiler supports two memory models. The small memory model enables 
the compiler to efficiently access memory by restricting the global data space 
to a single 64K-word data page. The big memory model allows unlimited data 
space. For more information, refer to subsection 2.3.1 on page 2-36. 

Compiler Shell Program 

The compiler package includes a shell program, which enables you to 
compile, assemble, and link programs in a single step. For more information, 
refer to Section 2.1 on page 2-2. 
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Flexible Assembly Language Interface 

The compiler has straightforward calling conventions, allowing you to easily 
write assembly and C functions that call each other. For more information, 
refer to Chapter 4, Runtime Environment. 

Integrated Preprocessor 

The C preprocessor is integrated with the parser, allowing for faster 
compilation. Standalone preprocessing or preprocessed listing is also 
available. For more information, refer to Section 2.2 on page 2-30. 


COFF Object Files 

Common object file format (COFF) allows you to define your system’s memory 
map at link time. This maximizes performance by enabling you to link C code 
and data objects into specific memory areas. COFF also provides rich support 
for source-level debugging. 

ROM-able Code 


For standalone embedded applications, the compiler enables you to link all 
code and initialization data into ROM, allowing C code to run from reset. 

Source Interlist Utility 

The compiler package includes a utility (clist) that interlists your original C 
source statements into the assembly language output of the compiler. This 
utility provides you with an easy method for inspecting the assembly code gen¬ 
erated for each C statement. For more information, refer to Section 2.6 on 
page 2-49. 

32-Bit and 40-Bit Data Sizes 

Data sizes char, short, int, long, float, and double are 32 bits. Data size long 
double is 40 bits. This allows all types of data to take full advantage of the 
TMS320C3x/C4x integer and floating-point arithmetic capabilities. For more 
information, refer to Section 3.2 on page 3-4. 


Library-Build Utility 
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A library-build utility called mk30 allows you to easily custom-build object 
libraries from source for any combination of runtime models or target CPUs. 
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C Compiler Description 


Translating your source program into code that the TMS320C3x/C4x can 
execute is a process consisting of several steps. You must compile, assemble, 
and link your source files to create an executable object file. The 
TMS320C3x/C4x package contains a special cl30 shell program that enables 
you to execute all of these steps with one command. This chapter provides a 
complete description of how to use the shell program to compile, assemble, 
and link your programs. 

The TMS320C3x/C4x C compiler includes an optimizer that allows you to pro¬ 
duce highly optimized code. The optimizer is explained in Section 2.4. 

The compiler package also includes a utility that interlists your original C 
source statements into the compiler’s assembly language output. This 
enables you to inspect the assembly language code generated for each C 
statement. The interlist utility is explained in Section 2.6. 

This chapter includes the following topics: 
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2.1 Compiling C Code. 

2.2 Controlling the Preprocessor _ 

2.3 Using Runtime Models . 

2.4 Using the C Compiler Optimizer .. 

2.5 Function Inlining. 

2.6 Using the Interlist Utility. 

2.7 How the Compiler Handles Errors 

2.8 Intrinsics. 

2.9 Invoking the Tools Individually ... 

2.10 Linking C Code . 
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2.1 Compiling C Code 


The cl30 shell program is a utility that lets you compile, assemble, and 
optionally link in one step. The shell runs one or more source modules through 
the following: 


The compiler 
The assembler 


which includes the parser, the optimizer, and the 
code generator. 

which generates a COFF object file. 


The linker which links your files to create an executable object 

(optional) file. The linker can be invoked as part of the larger 

process, or you can compile and assemble various 
files with the shell and link at a later time. 


For more information about the floating-point assembler and linker, refer to the 
TMS320C3x/C4x Assembly Language Tools User’s Guide. 


By default, the shell compiles and assembles files; however, if you use the 
-z option, the shell also links your files. Figure 2-1 illustrates the path the shell 
takes with and without the -z option. 


Figure 2-1. The cl30 Shell Program Overview 



2-2 



















































Compiling C Code 


2.1.1 Invoking the C Compiler 

To run the compiler, enter: 


cl30 

-options] [filenames] [~z[link_options] [object files]] 

cl30 

is the command that invokes the compiler and the 
assembler. 

-options 

affect the way the compiler processes input files. 

filenames 

are one or more C source files, assembly source files, or 
object files. 

-z 

is the option that runs the linker. 

link_options 

control the linking process. 

object files 

name the object files that the compiler creates. 


Options control how the compiler processes files, and the filenames provide 
a method of identifying source files, intermediate files, and output files. 
Options and filenames can be specified in any order on the command line. 
However, the -z option and its associated information must follow all filenames 
and compiler options on the command line. For example, if you wanted to com¬ 
pile two files named symtab and file, assemble a third file named seek.asm, 
and use the quiet option (-q), you would enter: 

cl30 -q symtab file seek.asm 

As cl30 encounters each source file, it prints the filename in square brackets 
[for C files] or angle brackets <for asm files>. The example above uses the 
-q option to suppress the additional progress information that cl30 produces. 
Entering the command above produces: 

[symtab] 

[file] 

<seek.asm> 
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The normal progress information consists of a banner for each compiler pass 
and the names of functions as they are defined. The example below shows the 
output from compiling a single module without the -q option. 

$ cl30 symtab 

[symtab] 

TMS320C3x/4x ANSI C Compiler Version x.xx 

Copyright (c) 1987-1997, Texas Instruments Incorporated 
"symtab.c":==> main 
"symtab.c":==> lookup 

TMS320C3x/4x ANSI C Codegen Version x.xx 

Copyright (c) 1987-1997, Texas Instruments Incorporated 
"symtab.c":==> main 
"symtab.c":==> lookup 

TMS320C3x/4x COFF Assembler Version x.xx 

Copyright (c) 1987-1997, Texas Instruments Incorporated 
PASS 1 
PASS 2 

No Errors, No Warnings 

2.1.2 Specifying Filenames 

The input files specified on the command line can be C source files, assembly 
source files, or object files. The shell uses filename extensions to determine 
the file type. 

Extension File Type 

.asm, .abs, or .s* (extension begins with s) assembly language source file 

.c or no extension C source file 

■o* (extension begins with o)object file 

Files without extensions are assumed to be C source files, and a .c extension 
is assumed. 

You can use the -e option to change these default extensions, causing the 
shell to associate different extensions with assembly source files or object 
files. You can also use the -f option on the command line to override these 
file type interpretations for individual files. For more information about the 
-e and -f options, refer to page 2-14. 

The conventions for filename extensions allow you to compile C files and 
assemble assembly files with a single command, as shown in the example on 
page 2-3. 

You can use wildcard filename specifications to compile multiple files. 
Wildcard specifications vary by system; use the appropriate form. 

To compile all the files in a directory that have a .c extension (by default, all C 
files), enter the following (DOS system): 
cl30 *.c 
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2.1.3 Compiler Options 

Command line options control the operation of both the shell and the programs 
it runs. This section provides a description of option conventions, an option 
summary table, and a detailed description of each of the options. 

Compiler options: 

□ Consist of single letters or letter groupings 

□ Are not case sensitive 

□ Are preceded by a hyphen 

□ Can be combined if there are single-letter options without parameters: for 
example, -sgq is equivalent to -s -g -q. 

□ Can be combined if two-letter pair options without parameters have the 
same first letter: for example, -mr and -mb can be combined as -mrb. 

□ Cannot be combined in a grouping that contains a two-letter pair option 
and a single-letter option. For example, -mrq is invalid, because it would 
be parsed as -mr and -mq. 

□ Cannot be combined with other options if they have parameters, such as 
-u name and -i dir. 

You can set up default options for the shell by using the C_OPTION environ¬ 
ment variable. For a detailed description of the C_OPTION environment 
variable, refer to subsection 2.1.4, Using the C_OPTION Environment 
Variable, on page 2-28. 

Table 2-1 summarizes all compiler options. The table is followed by in-depth 
descriptions of each of the options. 
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Table 2-1. Compiler Options Summary Table 


General Shell Options 

Option 

Effect 

These options control the 

-@filename 

causes the compiler shell to read 

overall operation of the 


options from the specified file 

cl30 shell. For more 
information, see page 

-c 

no linking (negates -z) 

2-12. 

-dname[=def] 

predefine a constant 


-g 

enable symbolic debugging 


-i dir 

define #include search path 


-k 

keep .asm file 


-msrevx 

specifies the silicon revision of the 
target chip to enable additional func¬ 
tionality for more recent silicon re¬ 
leases. Used in conjunction with -v 
flag. 

Example: 

-msrev6 -v31 : enable new (1996) 
’C31 parallel instructions 
-msrev2 - v32 : enable new (1996) 
’C32 parallel instructions 


-n 

compile only (create .asm file) 


-q 

suppress progress messages (quiet) 


-qq 

suppress all messages (super quiet) 


-s 

interlist optimizer comments and 
assembly source statements if avail¬ 
able; otherwise interlist C and 
assembly source statements 


-ss 

interlist C and assembly source 
statements 


-u name 

undefine a constant 


-vxx 

specify processor; xx = 30, 31,32, 

40, or 44 (default is -v30) (see also 
-ms rev) 


-z 

enable linking (all options following 
are passed to linker) 
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Table 2-1. Compiler Options Summary Table (Continued) 


File Specifiers 

Option 

Effect 

These options use the 

-ea 

set default extension for assembly 

extensions of each file- 


files 

name to determine how to 

-eo 

set default extension for obiect files 

process the tile. For more 

information, see page 

-fa file 

identify assembly language file (de- 

2-14. 


fault for .asm or .s*) 


-fc file 

identify C source file (default for .c or 
no extension) 


-to file 

identify object file (default for .o*) 


-\\dir 

specify object file directory 


-fs dir 

specify assembly file directory 


-ft 

override TMP environment variable 

Parser Options 

Option 

Effect 

These options control the 

-pe 

treat code-E errors as warnings 

preprocessing, syntax- 

-Pf 

generate prototypes for functions 

cnecKing, ana error- 

handling behavior of the 

-pk 

allow compatibility with pre-ANSI 

compiler. For more 


K&R C 

information, see page 

-pi 

generate preprocessed listing (.pp) 

2-16. 


file 


-pm 

combines source files to perform 
program-level optimization 


-pn 

suppress #line directives in .pp file 


-po 

preprocess only 


-pr 

write parser error messages to file 


-pwO (or -pw) 

suppress all warning messages 


-pwl 

enable serious warning messages 
(default) 


-pw2 

enable all warning messages 


-px filename 

names the output file created when 
using the -pm option 
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Table 2-1. Compiler Options Summary Table (Continued) 


These options control the 
preprocessing, syntax¬ 
checking, and error¬ 
handling behavior of the 
compiler. For more 
information, see page 

2-16. 

-p? 

enable trigraph expansion 

Inlining Options 

Options 

Effect 

These options control ex- 

-xO 

disable inlining 

pansion of functions de¬ 
clared as inline. For more 

—xl 

default inlining level 

information, refer to 
page 2-18. 

-x2 

define INLINE + invoke optimizer at 
level 2 

Type-Checking Options 

Option 

Effect 

These options allow 
relaxation of compiler 
ty^e-checking rules. For 

-tf 

relax prototype checking 

more information, refer to 
page 2-19. 

-tp 

relax pointer combination checking 
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Table 2-1. Compiler Options Summary Table (Continued) 


Runtime Model Options 

Options 

Effect 

These options are used to 
customize the executable 
output of the compiler for 
your specific application. 
For more information, see 
page 2-20. 

-ma 

-mb 

-me 

-mf 

assume aliased variables 

select big memory configuration 

use faster float to int conversions 

force indirect access to external 
objects, far data flag 


-mi 

disable RPTS instructions 


-ml 

use far calls for runtime support 
assembly calls 


-mm 

enable short multiply (’C3x only) 


-mn 

reenable optimizer options disabled 
by-g 


-mp 

perform speed operations at the cost 
of conservatively increased code 
size 


-mr 

use Tl register argument model 


-ms 

assume all memory is accessible 
when optimizing (see page 2-22) 


-mt 

generate Ada compatible frame 
structure 


-mtc 

generate legacy Tartan C function 
names 

Assembler Options 

Options 

Effect 

These options control the 
assembler’s behavior. For 
more information, see 
page 2-23. 

-aa 

-adname[=def] 

-al 

create absolute listing 

predefine a constant 

produce assembly listing file 


-as 

keep labels as symbols 


-au name 

undefine a constant 


-ax 

produce cross-reference file 
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Table 2- 


. Compiler Options Summary Table (Continued) 


Linker Options 

Options 

Effect 

These options are valid 

-a 

generate absolute output 

only when the compiler 
has been invoked with the 

-ar 

generate relocatable output 

-z option for linking. They 

-b 

disable the merging of symbolic 

control the linking 


debug information 

process. They must follow 
the -z option on the 

-c 

use ROM initialization 

command line, and the 

-cr 

use RAM initialization 

-z option must follow all 
other options and file¬ 
names on the command 

-esym 

-f val 

define entry point 

define fill value 

line. For more information, 

-g name 

keep named global symbol 

see page 2-23. 

-h 

regardless of the use of -h 

make all global symbols static 


-heap size 

set heap size (words) 


-heap8 size 

set heap size (words) for 8-bit 
memory (C32) 


-heapl 6 size 

set heap size (words) for 16-bit 
memory (C32) 


-i dir 

define library search path 


-1 lib 

supply library name 


-m file 

name the map file 


-n 

ignore all fill specifications in memory 
directives 


-o file 

name the output file 


-q 

suppress banner and progress infor¬ 
mation 


-r 

generate relocatable output 


-s 

strip symbol table 


-stack size 

set stack size (bytes) 


-u sym 

undefine entry point 


-vval 

generates version val COFF 


-w 

generate warning if output section is 
created that was not specified with 
SECTIONS directive 


-X 

force rereading of libraries 
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Table 2-1. Compiler Options Summary Table (Continued) 


Optimizer Options 

Options 

Effect 

These options control the 

-oO 

perform level 0 (register) optimization 

behavior of the optimizer. 
For more information, see 
page 2-26. 

—ol 

perform level 1 (level 0 + local) 
optimization 

-o2 (or -o) 

perform level 2 (level 1 + global) 
optimization 


-o3 

perform level 3 (level 2 + file) 
optimization 


-oi size 

set automatic inlining size (-o3 only) 


-olO (-oLO) 

specify that this file alters a standard 
library function 


-oil (-oLI) 

specify that this file defines a standard 
library function 


—ol2 (-oL2) 

specify that this file does not define or 
alter library functions 


-onO 

disable optimizer information file 


-onl 

produce optimizer information file 


-on2 

produce a verbose information file 


-opO 

specify that callable functions and/or 
modifiable variables are used in this 
module 


-opl 

specify that no callable functions are 
used in this module (default) 


-op2 

specify that no modifiable variables or 
callable functions are used in this 
module 


-op3 

specify that no modifiable variables 
are used in this module, but modifi¬ 
able functions may be used 


-os 

interlist optimizer comments with as¬ 
sembly source statements 


-ou 

allow zero-overhead loop operations 
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General Shell Options 

You can use the options described below to control the overall operation of the 
cl30 shell. 


-@filename 

read shell options and commands from a command file. 
The commands can be on one line or on several lines. 
Comments in the command file can begin with a semicolon 
(;) or a pound (#) character and end at the end of a line or 
can begin with the characters “/*” and end with Options 

in addition to those specified in the command file can be 
specified on the command line or with the C_OPTION 
environment variable. 

-c 

suppresses the linking option; it causes the shell not to run 
the linker even if -z is specified. This option is especially 
useful when you have -z specified in the C_OPTION 
environment variable and you don’t want to link. For more 
information, refer to page 2-67. 

-dname[=def\ 

predefines the constant name for the preprocessor. This is 
equivalent to inserting tfdefine name defat the top of each 

C source file. If the optional def is omitted, -d name sets 
name equal to 1. 

-g 

causes the compiler to generate symbolic debugging direc¬ 
tives that are used by the C source level debuggers and/or 
the interlist utility. 

-i dir 

adds dir to the list of directories to be searched for #include 
files. You can use this option a maximum of 32 times to de¬ 
fine several directories; be sure to separate -i options with 
spaces. Note that if you don’t specify a directory name, the 
preprocessor ignores the -i option. For more information, 
refer to subsection 2.2.2 on page 2-32. 

-k 

keeps the assembly language file. Normally, the shell de¬ 
letes the output assembly language file after assembling 
completes, but using -k allows you to retain the assembly 
language output from the compiler. 

-n 

causes the shell to compile only. If you use-n, the specified 
source files are compiled but not assembled or linked. This 
option overrides -z and -c. The output of -n is assembly 
language output from the compiler. 
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q 


qq 

s 


ss 


u name 


MXX 


suppresses banners and progress information from all the 
tools. Only source filenames and error messages are out¬ 
put. 


suppresses all output except error messages. 


interlists optimizer comments with assembly language out¬ 
put, if the comments are available; otherwise, this option 
invokes the interlist utility, which interlists C source state¬ 
ments into the compiler’s assembly language output. For 
more information, see Section 2.6, page 2-49. 


invokes the interlist utility, which interlists C source state¬ 
ments into the compiler’s assembly language output. For 
more information, see Section 2.6, page 2-49. 


undefines the predefined constant name. Overrides any -d 
options for the specified constant. 


specifies the target processor. Choices are: 

□ -v30 for a TMS320C30 processor 

□ -v31 for a TMS320C31 processor 

□ -v32 for a TMS320C32 processor 

□ -v40 for a TMS320C40 processor 

□ -v44 for a TMS320C44 processor 

By default, the tools produce code for the ’C30 processor. 
You must specify the appropriate option to generate code 
for the ‘C31, ’C32, ’C40, or ’C44. All code used in the 
eventual executable module, including all library-resident 
code, must be compiled under the same version. For more 
information, refer to Section 2.3 on page 2-35. 


enables the linking option. It causes the shell to run the link¬ 
er on specified object files. The -z option and its 
parameters follow all other compiler options and source 
files on the command line. All arguments that follow -z on 
the command line are passed to, and interpreted by, the 
linker. For more information, refer to subsection 2.10.1 on 
page 2-65. 
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File Specifiers 


-e allows you to change the default naming conventions tortile 

extensions for assembly language files and object files. 
This affects the interpretation of source filenames as well as 
the naming of files that the shell creates. 

The syntax for the -e option is: 

-ea[.] new extension for assembly language files 
-eo[.] new extension for object files 

For example: 

cl30 -ea .rrr -eo .odsp fit.rrr 

assembles the file fit.rrr and creates an object file named 
fit.odsp. 

The in the extension and the space between the option 
and the extension are optional. The example above could 
be written as: 

cl30 -earrr -eoodsp fit.rrr 

The -e option should precede any filenames on the com¬ 
mand line. If you don’t use the -e option, the default 
extensions are .asm for assembly files and .obj for object 
files. 
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overrides default interpretations for source file extensions. 
If your naming conventions do not conform to those of the 
shell, you can use -f options to specify which files are C 
source files, assembly files, or object files. You can insert 
an optional space between the -f option and the filename. 

The -f options are: 

-fa file for assembly source file 

-defile for C source file 

-fo file for object file 

For example, if you have a C source file called file.s and an 

assembly file called asmbly.asm, use -f to force the correct 
interpretation: 

cl30 -fcfile.s -fa asmbly 

Note that -f cannot be applied to a wildcard specification. 


permits you to specify a directory for object files. If the -fr 
option is not specified, the shell will place object files in the 
current directory. To specify an object file directory, insert 
the directory’s pathname on the command line after the -fr 
option: 

c!30 -fr d:\object ... 


permits you to specify a directory for assembly files. If the 
-fs option is not specified, the shell will place assembly files 
in the current directory. To specify an assembly file 
directory, insert the directory’s pathname on the command 
line after the -fs option: 

c!500 -fs d:\assembly ... 


permits you to specify a directory for temporary intermediate 
files. The -ft option overrides the TMP environment variable 
(described in subsection 2.1.5 ). To specify a temporary di¬ 
rectory, insertthe directory’s pathname on the command line 
after the -ft option: 

c!30 -ft d:\temp ... 
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Parser Options 


-pe treats code-E errors as warnings. Normally, the code 

generator does not run if the parser detects any code-E 
errors. When you use the -pe option, the parser treats 
code-E errors as warnings, allowing complete compilation. 
For more information about errors and about -pe, refer to 
Section 2.7 on page 2-51. 

-pf produces a function prototype listing file. The parser 

creates a file containing the prototype of every procedure 
in all corresponding C files. Each function prototype file is 
named as its corresponding C file, with a .pro extension, -pf 
is useful when conforming code to the ANSI C standard, or 
generating a listing of procedures defined. 

-pk relaxes certain requirements that are stricter than those 

required by earlier K&R compilers, and that are newly im¬ 
posed by the ANSI C standard. This facilitates compatibility 
between existing K&R-compatible programs and the 
TMS320C3x ANSI compiler. The effects of the -pk options 
are described in Section 3.10 on page 3-22. 

-pi generates a preprocessed listing file. The compiler writes 

a modified version of the source file to an output file called 
file.pp. This file contains all the source from #include files 
and expanded macros. It does not contain any comments. 
For more information, refer to subsection 2.2.3 on page 
2-34. 
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pm when used with the -o3 option, combines source files into 

one intermediate file called a module to perform program- 
level optimization instead of file-level optimization. The 
module proceeds to the optimization and code generation 
passes of the compiler. Because the compiler can now see 
the entire C program, it performs several optimizations that 
are not usually done during file-level optimization: 

□ If a particular argument in a function always has the 
same value, the compiler replaces the argument with 
the value and passes the value instead of the argu¬ 
ment. 

□ If a return value of a function is never used, the compiler 
deletes the return code in the function. 

□ If a function is not called, directly or indirectly, the com¬ 
piler removes the function. 

By default, the name of the resulting object file or assembly 
file is the same as the name of the first input C file. 

pn suppresses line and file information, -pn causes #line di¬ 

rectives of the form: 

#123 file.c. 

to be suppressed in a file generated with -po or -pi. You 
may find -pn useful when compiling machine-generated 
source. 

po runs the compiler for preprocessing only. When invoked 

with -po, the compiler processes only macro expansions, 
#include files, and conditional compilation. The compiler 
writes the preprocessed file with a .pp extension. For more 
information, refer to subsection 2.2.3 on page 2-34. 

pr creates a parser error message file. The error file has the 

base name of the input file and the .err extension. The file 
contains all error messages generated by the parser. 

pwn sets the warning message level. Section 2.7 on page 2-51 

discusses the diagnostic information reported by the com¬ 
piler. 

□ -pw or -pwO disables all warning messages. 

□ -pwl enables serious warning messages (default) 

□ -pw2 enables all warning messages 
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-px filename when using the -pm option, specifies the name of the final 
output file. For example, 

cl30 -pm one.c two.c three.c -px progl 

results in an object file named progl .obj. 

-p? enables trigraph expansion. Trigraphs are special escape 

sequences of the form: 

??c 

where c is a character. The ANSI C standard defines these 
sequences for the purpose of compiling programs on sys¬ 
tems with limited character sets. By default, the compiler 
does not recognize trigraphs; use -p? to enable trigraphs. 
For more information, refer to the ANSI specification, 
subsection 2.2.1.1. or K&R § A 12.1. 


Inlining Options 


-x n controls function inlining done by the optimizer when func¬ 

tions have been defined or declared as inline. The 
possibilities are: 

□ -xO disables all inlining 

□ —xl inlines all intrinsic operators (default) 

□ -x2 or -x invokes the optimizer at level 2 and defines 
the JNLINE preprocessor symbol, which causes all 
functions defined or declared as inline to be expanded 
in line 

Note that -xl is the default inlining option. It occurs whether 
or not the optimizer is invoked and whether or not any -x 
options are specified. The last option may be specified as 
-x or-x2 interchangeably. See Section 2.5 on page 2-43 for 
more details. 
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Type-Checking Options 

-tf relaxes type checking on redeclarations of prototyped 

functions. In ANSI C, if a function is declared with an old- 
format declaration, such as: 

int func ( ); 

and then later declared with a prototype, such as: 

int func(float a, char b); 

this generates an error because the parameter types in the 
prototype disagree with the default argument conversions 
(which convert float to double and char to int). With the -tf 
option, the compiler overlooks such redeclarations of 
parameter lists. 


-tp relaxes type checking on pointer combinations. This 

option has two effects: 

□ A pointer to a signed type can be combined in an 
operation with a pointer to the corresponding unsigned 
type: 

int *pi; 
unsigned *pu; 

pi = pu; /* Illegal unless -tp used */ 

□ Pointers to differently qualified types can be combined: 

char *p; 
const char *pc; 

p = pc; /* Illegal unless -tp used */ 

-tp is especially useful when you pass pointers to 
prototyped functions, because the passed pointer type 
would ordinarily disagree with the declared parameter type 
in the prototype. 
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Runtime-Model Options 

-ma 

-mb 

-me 


assumes that variables are aliased. The compiler assumes 
that pointers may alias (point to) named variables and 
therefore aborts certain optimizations when an assignment 
is made through a pointer. 

selects the big memory model, allowing unlimited space for 
global data, static data, and constants. In the small memory 
model, which is the default, this space is limited to 64K 
words. All code used in the eventual executable module, in¬ 
cluding all library resident code, must be compiled under 
the same model. For more information, refer to Section 2.3 
on page 2-35. 


uses faster float-to-int conversion. The ANSI C standard 
specifies that when an object of floating-point type is con¬ 
verted to an integer type, the fractional part is discarded, 
effectively rounding towards zero. The compiler uses the 
TMS320C3x/C4x FIX instruction for these conversions, 
which rounds toward negative infinity, followed by a four- 
instruction sequence to correct negative values. If the ANSI 
standard behavior is not important to your application, the 
-me option suppresses the correction sequence for faster 
execution. 
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mf forces the compiler to always honor indirection on external 

objects. The compiler allows objects not declared in the 
.bss section to be accessed indirectly via pointers, as 
described in subsection 4.5.2 on page 4-25. Such objects 
cannot be accessed directly because they are not on the 
data page addressed by the DP. In some cases the opti¬ 
mizer may convert such indirect accesses into direct 
accesses, possibly resulting in objects in the .bss being 
accessed incorrectly. For example: 

extern struct sss ext_obj; 

/* object not in .bss */ 
struct sss ext_ptr = &ext_obj 
/* object pointer */ 

The optimizer may convert an expression such as structure 
member ext_ptr—>f1 to ext_obj.fi because the optimizer 
assumes that all variables are in the .bss section. This 
transformation is invalid if ext_obj is not in the .bss section. 
The -mf option inhibits the transformation and preserves 
the indirection. 


mi disables the use of RPTS instructions for loops and uses 

RPTB instead. This allows loops to be interrupted. 


ml runtime support assembly calls use far calls. With this op¬ 

tion, calls to runtime support assembly arithmetic functions 
such as MPYJ30, DIVJ30, etc. will use 32-bit far calls of 
the form: 

LDI &MPY_130,Rx; CALLU Rx 

rather than the traditional 16-bit displacement form of CALL 
MPYJ30. See Section 3.8 on page 3-20 for more informa¬ 
tion on far calls. 


mm (TMS320C3x only) enables short multiplies, generating 

MPYI instructions for integer multiplies rather than runtime 
support calls. If your application does not need 32-bit 
integer multiplication, use -mm to enable the MPYI instruc¬ 
tion; it is significantly faster because it performs 24x24 bit 
multiplication using a single instruction rather than a call to 
a 32-bit library function. For more information, refer to 
Section 4.7 on page 4-32. 
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-mn 


-mp 


-mr 


-ms 


-mt 


-mtc 


re-enables the optimizations disabled by -g. If you use the 
-g option to generate symbolic debugging information, 
many code generator optimizations are disabled because 
they disrupt the debugger. 

performs speed optimizations at the cost of increased code 
size. The -mp option causes the code generator to 
increase code size when doing so will increase perfor¬ 
mance. This is most often seen in copying (rather than mov¬ 
ing) instructions into branch delay slots from the destination 
block. Refer to Section 3.9 on page 3-21 for further informa¬ 
tion on how the compiler handles branch delay slots. When 
this option is specified, the code generator may inline many 
commonly used functions, such as MPYJ30, to save the 
overhead of a function call. 

uses the register-argument model. Code compiled under 
this model is completely incompatible with code compiled 
under the default model. All code used in the eventual 
executable module, including all library resident code, must 
be compiled under the same model. For more information, 
refer to Section 2.3 on page 2-35. 

assumes all memory is accessible when optimizing. The 
-ms option causes the code generator to assume that no 
access to memory will cause the bus to block. See Section 
3.9 on page 3-21. 

causes the compiler to generate code that supports the 
Tartan Ada function calling conventions. 

generates an additional header for every C function 
compiled, allowing it to be used with the Tartan LAJ function 
calling method. Calling functions compiled with the 
TMS320C3x/C4x compiler from within Tartan-compiled 
code will exact a penalty of two cycles per call, but still 
allows some compatibility with existing Tartan assembly 
code and libraries. This option may be removed in a future 
release, so the legacy Tartan code should be recompiled. 


2-22 


Compiling C Code 


Assembler Options 


-aa invokes the assembler with the -a option, which creates 

an absolute listing. An absolute listing shows the abso¬ 
lute addresses of object code. 

-adname[=def\ predefines the constant name for the assembler. This 
is equivalent to inserting #define name defat the top of 
each source file. If the optional def is omitted, 

-ad name sets name equal to 1. 

-al invokes the assembler with the -I (lowercase L) option to 

produce an assembly listing file. 

-as retains labels. Label definitions are written to the COFF 

symbol table for use with symbolic debugging. 

-au name undefines the predefined constant name. Overrides 

any -ad options for the specified constant. 

-ax invokes the assembler with the -x option to produce a 

symbolic cross-reference in the listing file. 

For more information about assembler options, see the TMS320C3x/C4x 

Assembly Language Tools User’s Guide. 


Linker Options 


Linker options can be used with the compiler, or with the linker as a standalone. 
(See Section 2.10.2, Linking C Code, on page 2-66). When used with the 
compiler shell, all linker options should follow the -z option described in 
General Options, on page 2-12. For example: 

cl30 -q symtab.c -z -a -c -o symtab.out -1 rts30.1ib 

In this example, the file symtab.c will be compiled with the -q (quiet) option. 
The -z option causes the shell to invoke the linker and pass the -a, -c, -o, and 
-I linker options to the linker. 

All compiler command line options following -z are passed to the linker. For 
this reason, the -z option followed by the linker options must be the last shell 
option specified on the command line. All options on the command line follow¬ 
ing the -z option will be passed to the linker and not the compiler. 
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The -c and -n options suppress the linker option and cause the shell not to 
run the linker even if-z has been specified (see General Shell Options, page 
2-12, for more information.) Linker options are summarized in Table 2-1, 
Options Summary Table, beginning on page 2-6. For more information about 
linker options, refer to Section 2.10, page 2-65. 

For more information on the linker, see Chapter 8 of The TMS320C3x/C4x 
Assembly Language Tools User’s Guide. 


-a 

produces an absolute, executable module. This is the 
default; if neither -a nor -r is specified, the linker acts 
as if -a is specified. 

-ar 

produces a relocatable, executable object module. 

-b 

disables merging of symbolic debugging information. 

-c 

enables linking conventions defined by the ROM auto¬ 
initialization model of the TMS320C3x/4x C compiler. 
This is the default initialization method. 

-cr 

enables linking conventions defined by the RAM auto¬ 
initialization model of the TMS320C23x/4x C compiler. 

-e global_symbol 

defines a global_symbol that specifies the primary 
entry point for the output module. 

-f fill_value 

sets the default fill value for holes within output sec¬ 
tions; fill_value is a 16-bit constant. 

-g global_symbol 

instructs the linker to maintain the specified symbol as 
global, regardless of the use of the -h option. 

-h 

makes all global symbols static. 

-heap size 

sets heap size (for the dynamic memory allocation in 
C) to size words and defines a global symbol that spec¬ 
ifies the heap size. Default = 1K words. 

-heap8 size 

creates the C32 8-bit memory heap and sets heap size 
to size words and defines a global symbol that speci¬ 
fies the heap size. Default = 1K words, when needed. 

-heap16 size 

creates the C32 16-bit memory heap and sets heap 
size to size words and defines a global symbol that 
specifies the heap size. Default = IK words, when 
needed. 
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-i dir 

alters the library-search algorithm to look in dir before 
looking in the default location. This option must appear 
before the -1 option. The directory must follow operat¬ 
ing system conventions. 

-1 filename 

names an archive library file as linker input; filename 
is an archive library name, and must follow operating 
system conventions. 

-m filename 

produces a map or listing of the input and output 
sections, including holes, and places the listing in file¬ 
name. The filename must follow operating system con¬ 
ventions. 

-n 

instructs the linker to ignore all fill specifications in 
memory directives. 

-o filename 

names the executable output module. The default file¬ 
name is a.out, and must follow operating system con¬ 
ventions. 

-q 

suppresses banner and progress information. 

-r 

retains relocation entries in the output module. 

-s 

strips symbol table information and line number entries 
from the output module. 

-stack size 

sets the C system stack size to size words and defines 
a global symbol that specifies the stack size. Default = 
1K words. 

-u symbol 

places the unresolved external symbol symbol into the 
output module’s symbol table. 

-vn 

generates version n COFF format. 

-w 

generates a warning when an output section that is not 
specified with the SECTIONS directive is created. 

-X 

forces rereading of libraries, and resolves back 
references. 
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Optimizer Options 


-on causes the compiler to optimize the intermediate file that is 

produced by the parser, n denotes the level of optimization. 
There are three levels of optimizations: -oO, -ol, -o2, and 
-o3. 

If you do not indicate a level (0, 1,2, 3) after the -o option, 
the optimizer defaults to level 2. For more information about 
the optimizer, refer to Section 2.4 on page 2-38 and 
Appendix A. 

-oi size controls automatic inlining of functions (not defined or de¬ 

clared as inline) at optimization level 3. You specify the size 
limit for the largest function that will be inlined (times the 
number of times it is called). If no size is specified, the 
optimizer will inline only very small functions. Setting the size 
to 0 (—oiO) disables automatic inlining completely. Note that 
this option controls only the inlining of functions that have not 
been explicitly defined or declared as inline. The -x options 
control the inlining of functions declared as inline. 

-oln (lowercase L) controls file-level optimizations. When you 

invoke the optimizer at level 3 (-o3), it makes use of known 
properties of the standard library functions. If the file you are 
compiling redefines any of the standard functions, the 
compiler may produce incorrect code. Use the -oln options 
to notify the optimizer if any of the following situations exist: 

□ -olO: Use this option if the file you are compiling alters 
a standard library function. For example, if you have de¬ 
fined a function with the same name as a standard 
library function or you have altered the source code of 
a standard library function, use -olO to inform the opti¬ 
mizer not to assume the known properties of the stan¬ 
dard library function. 

□ -oil: Use this option if the file you are compiling con¬ 
tains unaltered definitions for standard library functions. 
For example, use -oil to compile the standard library. 

□ —ol2: Use this option to restore the default behavior of 
the optimizer after you have used one of the other two 
options in a command file, an environmentvariable, etc. 
Following the -ol2 option, the optimizer will use known 
properties of the standard library functions. 


2-26 


Compiling C Code 


-on n 


-op n 


-os 


-ou 


causes the compiler to produce a user readable optimization 
information file with a .nfo extension. This option works only 
when the -o3 option is used. There are three levels 
available: 

□ -onO do not produce an information file. Restores the 
default behavior of the optimizer if you have used one of 
the other two options in a command file, an environment 
variable, etc. 

□ -onl produce an optimization information file. 

□ -on2 produce a verbose optimization information file. 

specifies whether functions in other files can call this file’s 
EXTERN functions, or modify this file’s EXTERN variables. 
Level 3 optimization combines this information with its own 
file-level analysis to decide whether to treat this file’s 
EXTERN function and variable definitions as if they had 
been declared STATIC. The following levels are defined. 

□ -opO signals the optimizer that functions in this module 
may be called by other modules, and variables declared 
within the module may be altered by other modules. This 
disables some of the -o3 optimizations. 

□ -opl signals the optimizer that no functions in this 
module will be called by other modules and no interrupt 
functions declared elsewhere will call functions defined 
in this module. This is the default when -o3 is used. 

□ -op2 or -op signals the optimizer that no functions in 
this module are called by other modules and no variable 
declared in this module will be altered by another 
module. 

□ -op3 signals the optimizer that functions in this module 
may be called by other modules, but no variables 
declared within the module may be altered by other 
modules. This disables some of the -o3 optimizations. 


interlists optimizer comments into the compiler’s assembly 
language output. For more information, see Section 2.6, 
page 2-49. 


allows the compiler to use zero-overhead loop instructions, 
RPTS and RPTB to control unsigned loop counters. To use 
this option, you must be certain that these loops will iterate 
fewer than 2 31 times. 
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2.1.4 Using the C_OPTION Environment Variable 

An environment variable is a system symbol that you define and assign to a 
string. You may find it useful to set the shell default options using the 
C_OPTION environment variable; if you do this, these default options and/or 
input filenames are used every time you run the shell. 

Setting up default options with the C_OPTION environment variable is 
especially useful when you want to run the shell consecutive times with the 
same set of options and/or input files. After the shell reads the entire command 
line and the input filenames, it reads the C_OPTION environment variable and 
processes it. 

Options specified with the environment variable are specified in the same way 
and have the same meaning as they do on the command line. 

For example, if you want to always run quietly, enable symbolic debugging, 
and link, then set up the C_OPTION environment variable as follows: 


Host 

Enter 

DOS or OS/2 

set C_OPTION=-qg -z 

UNIX 

setenv C OPTION ”-qg -z” 


You may want to set C_OPTION in your system initialization file; for example, 
on PCs, in your autoexec.bat file. 

Using the -z option enables linking. If you plan to link most of the time when 
using the shell, you can specify the -z option with C_OPTION. Later, if you 
need to invoke the shell without linking, you can use -c on the command line 
to override the -z specified with C_OPTION. These examples assume 
C_OPTION is set as shown previously: 


cl30 *.c 
cl30 -c *.c 
cl30 *.c -z c.cmd 
c!30 -c *.c -z c.cmd 


compiles and links 
only compiles 

compiles/links using command file 
only compiles (-c overrides -z) 


2.1.5 Using the TMP Environment Variable 

The shell program creates intermediate files as it processes your program. For 
example, the parser phase of the shell creates a temporary file used as input 
by the code generation phase. By default, the shell puts intermediate files in 
the current directory. However, you can name a specific directory for 
temporary files. 

This feature allows use of a RAM disk or other high-speed storage files. It also 
allows source files to be compiled from a remote directory without writing any 
files into the directory where the source resides. This is useful for protected 
directories. 
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There are two ways to specify a temporary directory: 

1) Use the TMP environment variable: 

set TMP=d:\temp 

This example is for a PC. Use the appropriate command for your host. 

2) Use the -ft option on the command line: 

cl30 -ft d:\temp.... 

The -ft option, if used, overrides the TMP environment variable. 
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2.2 Controlling the Preprocessor 

The TMS320C3x/C4x C compiler includes standard C preprocessing func¬ 
tions, which are built into the first pass of the compiler (parser). The 
preprocessor handles: 

□ Macro definitions and expansions 

□ #include files 

□ Conditional compilation 

□ Various other preprocessor directives (specified in the source file as lines 
beginning with the # character) 

This section describes specific features of the TMS320C3x/C4x preprocessor. 
A general description of C preprocessing is in Section A12 of K&R. 
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2.2.1 Predefined Names 

The compiler maintains and recognizes the predefined macro names listed in 
Table 2-2: 

Table 2-2. Predefined Macro Names 


Macro Name 

Description 

_LINE_t 

expands to the current line number 

_FILE_t 

expands to the current source filename 

_DATE_t 

expands to the compilation date, in the form mm dd yyyy 

_TIME_t 

expands to the compilation time, in the form hh:mm:ss 

_STDC_t 

expands to 1 (identifies the compiler as ANSI standard) 

C3x 

_TMS320C3x 

expands to 1 if the target processor is a TMS320C3x 
processor, otherwise it is undefined. 

C30 

_TMS320C30 

expands to 1 if target processor is defined to be TMS320C30, 
otherwise it is undefined. 

C31 

_TMS320C31 

expands to 1 if target processor is defined to be TMS320C31, 
otherwise it is undefined. 

_C32 

_TMS320C32 

expands to 1 if target processor is defined to be TMS320C32, 
otherwise it is undefined. 

C4x 

_TMS320C4x 

expands to 1 if the target processor is a TMS320C4x 
processor, otherwise it is undefined. 

C40 

_TMS320C40 

expands to 1 if the target processor is a TMS320C40 
processor, otherwise it is undefined. 

C44 

_TMS320C44 

expands to 1 if the target processor is a TMS320C44 
processor, otherwise it is undefined. 

_INLINE 

expands to 1 under the -x or -x2 optimizer option, undefined 
otherwise 

_REGPARM 

expands to 1 if the register argument runtime model is used, 
undefined otherwise. 

_BIGMODEL 

expands to 1 if the -mb option is used, undefined otherwise. 


t Specified by the ANSI standard 


You can use macro names in the same manner as any other defined name. 
For example: 

printf (" %s %s" ,_TIME_, _DATE_); 

could translate to a line such as: 

printf (" %s %s", "Jan 14 1997", "13:58"17"); 
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The preprocessor produces self-explanatory error messages. The line 
number and the filename where the error occurred are printed along with a 
diagnostic message. 

You can predefine additional names from the command line by using the 
-d option: 

cl30 -dNAME -dREGS=6 *.c 

This has the same effect as including these lines at the beginning of each 
source file: 

#define NAME 1 
#define REGS 6 

2.2.2 #include File Search Paths 


The #include preprocessor directive tells the compiler to read source 
statements from another file. The syntax for this directive is: 


#include 

"filename” 

or 


#include 

<filename> 


The filename names the #include file that the compiler reads statements from. 
You can enclose the filename in double quotes or in angle brackets. The 
filename can be a complete pathname, have partial path information, or have 
no path information. 

□ If you enclose the filename in double quotes, the compiler searches for the 
file in the following directories, in the order given: 

1) The directory that contains the current source file. (The current source 
file refers to the file that is being compiled when the compiler 
encounters the #include directive.) 

2) Any directories named with the -i compiler option in the shell. 

3) Any directories set with the environment variable C_DIR. 

□ If you enclose the filename in angle brackets, the compiler searches for 
the file in the following directories, in the order given: 

1) Any directories named with the -i option in the shell. 

2) Any directories set with the environment variable C_DIR. 

Note that if you enclose the filename in angle brackets, the compiler 
does not search for the file in the current directory. 

Include files are sometimes stored in directories. You can augment the 
compiler’s directory search algorithm by using the -i shell option or the 
environment variable C_DIR to identify a directory name. 
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-/' Shell Option 

The -i shell option names an alternate directory that contains #include files. 
The format for the -i option is: 

c!30 -i pathname... 


You can use up to 32 -i options per invocation; each -i option names one 
pathname. In C source, you can use the #include directive without specifying 
any path information for the file; instead, you can specify the path information 
with the -i option. For example, assume that a file called source.c is in the 
current directory. This file contains one of the following directive statements: 

#include "alt.h" or 
#include <alt.h> 

The table below lists the complete pathname for alt.c and shows how to invoke 
the compiler; select the row for your host system. 


Host 

Pathname for alt.c 

Invocation Command 

DOS or OS/2 

c:\dsp\files\alt.h 

cl30 -ic:\dsp\files source.c 

UNIX 

/dsp/files/alt.h 

c!30 -i/dsp/files source.c 


C_DIR Environment Variable 

The compiler uses the environment variable C_DIR to name alternate 
directories that contain #include files. To specify the same directory for 
#include files, as in the previous example, set C_DIFt with one of these 
commands: 


Host 

Enter 

DOS or OS/2 

set C_DIR=c:\dsp\files 

UNIX 

setenv C DIR /dsp/files 


Then you can include alt.h: 

#include "alt.h" or 
#include <alt.h> 

and invoke the compiler without the -i option: 
cl30 source.c 

This results in the compiler using the path in the environment variable to find 
the #include file. 

The pathnames specified with C_DIR are directories that contain #include 
files. You can separate pathnames with a semicolon or with blanks. In C 


C Compiler Description 


2-33 









Controlling the Preprocessor 


source, you can use the #include directive without specifying any path infor¬ 
mation; instead, you can specify the path information with C_DIR. 


The environment variable remains set until you reboot the system or reset the 
variable by entering one of these commands: 


Host 

Enter 


DOS or OS/2 

set 

C_DIR= 

UNIX 

unsetenv 

C DIR 


2.2.3 Generating a Preprocessed Listing File (-pi, -pn, -po Options) 

The -pi shell option allows you to generate a preprocessed version of your 
source file. The compiler’s preprocessing functions perform the following 
actions on the source file: 

□ Each source line ending in backslash (\) is joined with the following line. 

□ Trigraph sequences are expanded (if enabled with the -p? option). 

□ Comments are removed. 

□ #include files are copied into the file. 

□ Macro definitions are processed, and all macros are expanded. 

□ All other preprocessing directives, including #line directives and 
conditional compilation, are executed. 

(These functions correspond to translation phases 1 -3 as specified in Section 
A12 of K&R.) 

The preprocessed output file contains no preprocessor directives other than 
#line; the compiler inserts #line directives to synchronize line and file 
information in the output files with input position from the original source files. 
If you use the -pn option, no #line directives are inserted. 

If you use the -po option, the compiler performs only the preprocessing 
functions listed above and then writes out the preprocessed listing file; no 
syntax checking or code generation takes place. The -po option can be useful 
when debugging macro definitions or when host memory limitations dictate 
separate preprocessing (refer to Parsing in Two Passes on page 2-59). The 
resulting preprocessed listing file is a valid C source file that can be rerun 
through the compiler. 
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2.3 Using Runtime Models 

The compiler has three options that allow you to affect the runtime model. All 
linked modules must use the same runtime model in order to correctly 
interface with other C modules, assembly modules, and library resident mod¬ 
ules. Runtime models are mutually exclusive, that is, you must choose a con¬ 
figuration and then make sure that all the modules you link use the same 
model. The following conventions are mutually exclusive and must be chosen 
before you begin to compile: 

Mutually Exclusive Runtime Model Options 

big memory model (-mb) small memory model (default) 

register-argument model (-mr) stack-based model (default) 

TMS320C4X model (~v40, -v44)TMS320C3x model (—v30, -v31, -v32) 

All code linked together in any program, including assembly language and 
library modules, must agree on these three options. Mixed model code may 
link without error, but it will not run correctly. The linker will issue an error mes¬ 
sage if you try to link TMS320C4x code with TMS320C3x code. The big and 
small memory models are further explained in subsection 2.3.1, page 2-36. 
Register-argument and stack-based models are explained in subsection 
2.3.2, page 2-37. With these exceptions, compiler options including runtime 
model options do not affect compatibility with other modules. 

Eight runtime libraries are shipped with the compiler. All are compiled for the 
small memory model convention: 


Runtime Library 

Processor 

Model Option(s) Used 

rts30.lib 

TMS320C3X 

small memory model; 
stack-based model 

rts30g.lib 

TMS320C3X 

stack-based model; includes 
symbolic debugging information 

rts30r.lib 

TMS320C3X 

register-argument model 

rts30gr.lib 

TMS320C3X 

register-argument model; includes 
symbolic debugging information 

rts40.lib 

TMS320C4X 

small memory model; 
stack-based model 

rts40g.lib 

TMS320C4X 

stack-based model; includes 
symbolic debugging information 

rts40r.lib 

TMS320C4X 

register-argument model 

rts40gr.lib 

TMS320C4X 

register-argument model; includes 
symbolic debugging information 
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Refer to Section 5.1 for further information. If you want to use a model that is 
incompatible with these, you must build a compatible version of the runtime 
library with the library build utility (mk30). See Chapter 6 for more information 
on using this utility. 

By default, the mk30 utility will create a runtime-support library called rts.lib. 
However, if you use more than one library, you may wish to adopt a naming 
convention that makes it obvious which models were used. For example, 
append a suffix that contains the target CPU number (30 or 40), an ‘r’ for the 
register-argument model, and a ‘b’ for the big model. Thus rts40rb.lib would 
be easily recognized as the runtime support library for the TMS320C4x, big 
model, with the register-argument runtime model, and rts30.lib would be for 
the TMS320C3x small model and stack-based or standard runtime model. 

2.3.1 The Big and Small Memory Models 

The small memory model (default) requires that all external variables, global 
variables, static variables, and compiler-generated constants in the program 
(after linking) fit into a single 64K word long data page (65536 words). This 
allows the compiler to access any of these objects without modifying the data 
page pointer (DP) register. Neither model restricts the size of code, automatic 
data, or dynamically allocated data. 

The big model (-mb option) removes the 64K restriction. However, this model 
also forces the compiler to reload the data page pointer before accessing any 
external variables or compiler generated constants. This is less efficient since 
it forces an extra instruction and possibly one or more extra pipeline delay 
cycles each time the compiler accesses one of these objects. 

Use the small model whenever possible. If you have large arrays, allocate 
them dynamically from the heap (using malloc) rather than declaring them as 
global or static. 

I-1 

Note: Size Restrictions on Small Model are not Tested 

When you use the small model, you must be sure the .bss section is less than 
64K words and does not cross any 64K page boundaries. Neither the 
compiler nor the linker checks these restrictions against the model used. 

To make sure that the .bss section conforms to these two rules, link the 
.bss section using the block attribute of the SECTIONS directive. 

I_I 

The statement: 

.bss: load = block (0x10000) 

when used with the SECTIONS directive, will force the .bss section into a 64K 
data page if the size of the .bss section is less than 64K. You should check the 
link map after linking to verify that the .bss does not violate the restrictions. 
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If you have variables declared in assembly language outside the .bss section, 
you can still use the small model, but you must access them indirectly, and you 
may need to use the -mf option as well. Section 4.5 on page 4-22 discusses 
interfacing C with assembly language. 

2.3.2 The Register-Argument and Standard Models 

You can choose from two different argument passing models. In the standard 
runtime model (default) the compiler passes all arguments to functions on the 
stack. When you invoke the compiler with the -mr option, some or all of the 
arguments are passed in registers. This results in less overhead for function 
calls in your program. 

I-1 

Note: All Functions Must Be Prototyped 

When using the register-argument model, all functions must be prototyped. 
The compiler must be able to “see” the types of function parameters when 
the function is called. If there is a function call with no prototype visible, the 
compiler probably will generate incorrect code for the call. The -pf option will 
generate prototypes for all functions you define. The -pw2 option will issue 
a warning for a function call that has no prototype in scope. 

I_I 

The runtime-support libraries rts30r.lib, rts30gr.lib, rts40r.lib, and rts40gr,lib 
(shipped with the compiler) are compatible with the register-argument model. 

Technical details of both models are explained in Section 4.4 on page 4-15. 
The library build utility is described in Chapter 6. 
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2.4 Using the C Compiler Optimizer 

The compiler package includes an optimization program that improves the 
execution speed and reduces the size of C programs by doing such things as 
simplifying loops, rearranging statements and expressions, and allocating 
variables into registers. 

The optimizer runs as a separate pass between the parser and the code 
generator. The easiest way to invoke the optimizer is to use the cl30 shell 
program, specifying the -o option on the cl30 command line (you may also 
invoke the optimizer outside cl30; refer to Section 2.9 on page 2-56 for more 
information). The -o option may be followed by a digit specifying the level of 
optimization. If you do not specify a level digit, the default is level 2. 

For example, to invoke the compiler using full optimization with inline function 
expansion, enter: 

cl30 -o3 -x function.c 

Figure 2-2 illustrates the execution flow of the compiler with standalone 
optimization. 

Figure 2-2. Compiling a C Program with the Optimizer 



The optimizer also recognizes cl30 options -s, -ma, -q, and -pk; these 
options are discussed in subsection 2.1.3. 

To invoke the optimizer outside c!30, refer to subsection 2.9.2. 
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2.4.1 Optimization Levels 

There are four levels of optimization: 0, 1,2, and 3. These levels control the 
type and degree of optimization. 

□ Level 0 

■ performs control-flow-graph simplification 

■ allocates variables to registers 

■ performs loop rotation 

■ eliminates dead code 

■ simplifies expressions and statements 

■ expands calls to functions declared as inline 

□ Level 1 

performs all level 0 features, plus: 

■ performs local copy/constant propagation 

■ removes local dead assignments 

■ eliminates local common subexpressions 

□ Level 2 

performs all level 1 features, plus: 

■ performs loop optimizations 

■ eliminates global common subexpressions 

■ eliminates global redundant assignments 

■ converts array references in loops to incremented pointer form 

■ performs loop unrolling 

□ Level 3 

performs all level 2 features, plus: 

■ removes all functions that are never called 

■ simplifies functions that have return values that are never used 

■ expands calls to small functions inline 

■ reorders function definitions so the attributes of called functions are 
known when the caller is optimized 

■ propagates arguments into function bodies when all call sites pass the 
same value in the same argument position 

■ identifies file-level variable characteristics 
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I-1 

Note: Files That Redefine Standard Library Functions 

The optimizer uses known properties of the standard library functions to 
perform level 3 optimizations. If you have files that redefine standard library 
functions, use the -ol (lowercase L) options to inform the optimizer. 
(See page 2-26.) 

I_I 

This list describes optimizations performed by the standalone optimization 
pass. The code generator performs several additional optimizations, 
particularly TMS320C3x/C4x-specific optimizations; it does so regardless of 
whether or not you invoke the optimizer. These optimizations are always 
enabled and are not affected by the optimization level you choose. 

For more information about the meaning and effect of specific optimizations, 
refer to Appendix A. 

2.4.2 Definition Controlled Inline Expansion Option (-x Option) 

When the optimizer is invoked, the -x optimizer option controls inline 
expansion of functions that have been declared as inline by inhibiting or 
allowing the expansion of their code in place of calls. That is, code for the 
function will be inserted (inlined) into your function at each place it is called 
whenever the optimizer is invoked and the -x option is not equal to -xO. The 
-x2 option automatically invokes the optimizer at the default level (level 2, if 
the -o option is not specified separately) and defines the JNLINE preproces¬ 
sor symbol as equal to 1, which causes expansion of functions declared as in¬ 
line and controlled by the JNLINE symbol (For more information about 
JNLINE, see subsection 2.5.3, page 2-46). 

Inlining makes a program faster by eliminating the overhead caused by 
function calls, but inlining sometimes increases code size. 

For more information, see Section 2.5, Function inlining, page 2-43. 

2.4.3 Using the Optimizer with the Interlist Option (-os option) 

Optimization makes normal source interlisting impractical, because the 
optimizer extensively rearranges your program. Therefore, the optimizer 
writes reconstructed C statements (as assembly language comments), which 
show the optimized C statements. The comments also include a list of the 
allocated register variables. Note that occasionally the optimizer interlist 
comments may be misleading because of copy propagation or assignment of 
multiple or equivalent variables to the same register. 

2.4.4 Debugging Optimized Code 

The best way to debug code that is also optimized is to debug it in an 
unoptimized form and then reverify its correctness after it has been optimized. 
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The debugger may be used with optimized code, but the extensive rearrange¬ 
ment of code and the many-to-one allocation of variables to registers often 
makes it difficult to correlate source code with object code. 

I-1 

Note: Symbolic Debugging and Optimized Code 

If you use the -g option to generate symbolic debugging information, many 
code generator optimizations are disabled because they disrupt the 
debugger. If you want to use symbolic debugging and still generate fully 
optimized code, use the -mn option on cl30; -mn re-enables the 
optimizations disabled by -g. 

I_I 

2.4.5 Special Considerations When Using the Optimizer 

The optimizer is designed to improve your ANSI-conforming C programs while 
maintaining their correctness. However, when you write code for the optimizer, 
you should note the following special considerations to insure that your 
program performs as you intend. 

asm Statements 

You must be extremely careful when using asm (inline assembly) statements 
in optimized code. The optimizer rearranges code segments, uses registers 
freely, and may completely remove variables or expressions. Although the 
compiler will never optimize out an asm statement (except when it is totally 
unreachable), the surrounding environment where the assembly code is 
inserted may differ significantly from its apparent context in the C source code. 
It is usually safe to use asm statements to manipulate hardware controls such 
as interrupt registers or I/O ports, but asm statements that attempt to interface 
with the C environment or access C variables may have unexpected results. 
After compilation, check the assembly output to make sure your asm 
statements are correct and maintain the integrity of the program. 

Volatile Keyword 


The optimizer analyzes data flow to avoid memory accesses whenever 
possible. If you have code that depends on memory accesses exactly as 
written in the C code, you must use the volatile keyword to identify these 
accesses. The compiler won’t optimize out any references to volatile 
variables. 

In the following example, the loop waits for a location to be read as OxFF: 

unsigned int *ctrl; 
while (*ctrl !=0xFF); 
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In this example, *ctrl is a loop-invariant expression, so the loop will be 
optimized down to a single memory read. To correct this, declare Ctrl as: 


volatile unsigned int *ctrl 


Aliasing 


Aliasing occurs when a single object may be accessed in more than one way, 
such as when two pointers point to the same object or when a pointer points 
to a named object. Aliasing can disrupt optimization because any indirect 
reference could potentially refer to any other object. The optimizer analyzes 
the code to determine where aliasing can and cannot occur, then optimizes as 
much as possible while still preserving the correctness of the program. 

The compiler assumes that if the address of a local variable is passed to a 
function, the function might change the local by writing through the pointer but 
will not make its address available for use elsewhere after returning. For 
example, the called function cannot assign the local’s address to a global 
variable or return it. In cases where this assumption is invalid, use the 
-ma option in cl30 to force the compiler to assume worst-case aliasing. In 
worst-case aliasing, any indirect reference may refer to such a variable. 
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2.5 Function Inlining 

When an inline function is called and the optimizer is invoked, the code for the 
function is inserted at the point of the call. This is advantageous in short 
functions for two reasons: 

□ It saves the overhead of a function call. 

□ Once inlined, the optimizer is free to optimize the function in context with 
the surrounding code. 

Inline expansion is performed one of three ways. 

□ The intrinsic operators of the target system (such as abs) are inlined by 
the compiler by default. This happens whether or not the optimizer is used 
and whether or not any compiler or optimizer options are used. (You can 
defeat this automatic inlining by invoking the compiler with the -xO option.) 

□ Definition controlled inline expansion is performed when two conditions 
exist: 

■ the inline keyword is encountered in source code 
and 

■ the optimizer is invoked (at any level) 

Functions with local static variables or a variable number of arguments will 
not be inlined, with the exception of functions declared as static inline. In 
functions defined as static inline, expansion will occur despite the pres¬ 
ence of local statics. In addition, a limit is placed on the depth of inlining for 
recursive or non-leaf functions. Inlining should be used for small functions 
or functions that are called only a few times (though the compiler does not 
enforce this.) 

You can control this type of function inlining two ways: 


inline return-type function-name (parameter declarations) {function} 


■ Method 1. By defining a function as inline within a module (with the 
inline keyword), you can specify that the function is inlined within that 
module. A global symbol for the function is created, but the function 
will be inlined only within the module where it is defined as inline. It will 
be called by other modules unless they contain a compatible static 
inline declaration. Functions defined as inline are expanded when the 
optimizer is invoked and the -x option is not equal to -xO. Setting the 
-x option to -x2 will automatically invoke the optimizer at the default 
level (level 2). 
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static inline return-type function-name (parameter declarations) 


■ Method 2. By declaring a function as static inline, you can specify that 
the function is inlined in the present module. This names the function 
and specifies that the function is to be expanded inline, but no code is 
generated for the function declaration itself. Functions declared in this 
way may be placed in header files and included by all source modules 
of the program. Declaring a function as static inline in a header file 
specifies that the function is inlined in any module that includes the 
header. 

Functions declared as inline are expanded whenever the optimizer is 
invoked at any level. Functions declared as inline and controlled by 
the JNLINE preprocessor symbol, such as the runtime library func¬ 
tions, are expanded whenever the optimizer is invoked and the 
JNLINE preprocessor symbol is equal to 1. When you define an inline 
function, it is recommended that you use the JNLINE preprocessor 
symbol to control its declaration. If you fail to control the expansion 
using JNLINE, and subsequently compile without the optimizer, the 
call to the function will be unresolved. For more information, see 
subsection 2.5.3, The_INLINE Preprocessor Symbol, page 2-46. 

□ Automatic inline expansion (functions nofdeclared as inline) is done when 
the optimizer is invoked at level 3. By default, the optimizer will inline very 
small functions. You can change the size of functions that are 
automatically inlined with the -oi size option. The -oi option specifies that 
functions whose size (times number of calls) is less than size units are in- 
lined regardless of how they were declared. The optimizer measures the 
size of a function in arbitrary units. However, the size of each function is 
reported in the optimizer information file (-onl option). If you want to be 
certain that a function is always inlined, use the inline keyword (discussed 
above and in the next subsection). You can defeat all automatic inlining of 
small functions not declared as inline by setting the size to 0 (—oiO). 


I-1 

Note: Function Inlining May Greatly Increase Code Size 

It should be noted that expanding functions inline expands code size, and 
that inlining a function that is called a great number of times can expand code 
size exponentially. Function inlining is optimal for functions that are called 
only a small number of times, or for small functions that are called more often. 
If your code size seems too large, try compiling with the -xO keyword and 
note the difference in code size. 

I_I 
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2.5.1 Controlling Inline Expansion (-x Option) 

A command line switch controls the types of inline expansion performed. 

-xO : no inline expansion. Defeats the default expansions listed below. Ifthe 
-xO shell option is specified, the compiler treats intrinsic functions as 
regular function calls. See Section 2.8 on page 2-54 for further 
information on intrinsics. 

—xl : is the default value. The intrinsic operators are inlined wherever they 

are called. This is true whether or not the optimizer is invoked, and 
whether or not a-x option is specified (except-xO). Intrinsic operators 
are listed on page 2-54. 

-x2/-x: creates the preprocessor symbol INLINE, assigns it the value 1, and 
invokes the optimizer at level 2, thereby enabling definition controlled 
inline expansion. 

If a function has been defined or declared as inline, it will be expanded 
inline whenever the optimizer is called and the -x option is not equal 
to -xO. Setting the -x option to -x2 automatically invokes the optimizer 
and thus causes the automatic expansion of functions defined or 
declared as inline, as well as causing the other optimizations defined 
at level 2, which is the default level for the optimizer. The JNLINE 
preprocessor symbol has been used to control the expansion of the 

runtime library modules. They will be expanded if_INLINE is equal to 

1, but will be called if JNLINE is not equal to 1. Other functions may 
be set up to use JNLINE in the same way. For more information, see 
subsection 2.5.3, The JNLINE Preprocessor Symbol. 

If the -x, -xl or -x2 option is used together with the -o option at any 
level, the optimizer will be invoked at the level specified by -o rather 
than at the level specified by -x. 


2.5.2 Automatic Inline Expansion Option (-oi size Option) 

The optimizer will automatically inline all small functions (not defined or de¬ 
clared with the inline keyword) when invoked at level 3. A command line option 
controls the size of functions inlined when the optimizer is invoked at level 3. 
The -oi option can be used three ways: 

□ If you set the size parameter to zero (—oiO), all size controlled inlining is 
disabled. 

□ If you do not use the -oi option, the optimizer inlines very small functions. 
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□ If you set the size parameter to a nonzero integer, the optimizer will inline 
all functions whose size is less than the size parameter. If the function is 
called more than once, the optimizer multiplies the size of the function by 
the number of calls, and will inline the function only if the resulting product 
is less than the size parameter. The optimizer measures the size of a 
function in arbitrary units. The optimizer information file (created with the 
-onl or -on2 option), however, will report the size of each function in the 
same units that the -oi option uses. 

2.5.3 INLINE Preprocessor Symbol 

JNLINE is a preprocessor symbol that is defined (and set to 1) if the parser 
(or shell utility) is invoked with the -x2 (or-x) option. It allows you to write code 
so that it will run whether or not inlining is used. It is used by standard header 
files included with the compiler to control the declaration of standard C runtime 
functions. 

The JNLINE symbol is used in the string.h header file to declare the function 
correctly, regardless of whether inlining is used. The JNLINE symbol is turned 
off in the memcpy source before the header file is included, because it is 
unknown whether the rest of the module is compiled with inlining. 

If the rest of the modules are compiled with inlining enabled and the string.h 
header is included, all references to memcpy will be inlined and the linker will 
not have to use the memcpy in the runtime-support library to resolve any 
references. Otherwise, the runtime-support library code will be used to resolve 
the references to memcpy and function calls will be generated. 

You will wantto use the JNLINE preprocessor symbol in the same way so that 
your programs will run regardless of whether inlining mode is selected for any 
or all of the modules in your program. 

Example 2-1 on page 2-47 illustrates how the runtime support library uses the 
JNLINE symbol. 
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Example 2-1. How the Runtime Support Library Uses the _INLINE Symbol 

/****************************************************************************/ 
/* STRING.H HEADER FILE */ 

/****************************************************************************/ 
typedef unsigned size_t 

#if _INLINE 

tdefine_INLINE static inline 

#else 

#define _INLINE 

#endif 

_INLINE void *memcpy (void *_sl, const void *_s2, size_t _n); 

#if _INLINE /* Declare the inlined function */ 

static inline void *memcpy (void *to, const void *from, size_t n) 

{ 

register char *rto = (char *) to; 
register char *rfrom = (char *) from; 
register size_t rn; 

for (rn = 0; rn < n; rn++) *rto++ =rfrom++; 
return (to); 

} 

#endif /* _INLINE */ 

#undef INLINE 

/****************************************************************************/ 
/* MEMCPY.C (rtsxx.lib) */ 

/****************************************************************************/ 
tundef _INLINE /* Turn off so code will be generated */ 

tinclude <string.h> 

void *memcpy (void *to, const void *from, size_t n) 

{ 

register char *rto = (char *) to; 
register char *rfrom = (char *) from; 
register size_t rn; 

for (rn = 0; rn < n; rn++) *rto++ =rfrom++; 
return (to); 

} 


/* Declaration when inlining */ 

/*No declaration when not inlining*/ 


There are two definitions of the memcpy function. The first, in the header file 
is an inline definition. Note how this definition is enabled and the prototype 
declared as static inline only if JNLINE is true: that is, the module including 
this header is compiled with the -x option. 

The second definition (in memcpy.c) is for the library so that the callable 
version of memcpy exists when inlining is disabled. Since this is not an inline 
function, the JNLINE symbol is undefined (#undef) before including string.h 
so that the non-inline version of memcpy’s prototype is generated. 
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If the application is compiled with the -x option and the string.h header is 
included, all references to memcpy in the runtime support library will be inlined 
and the linker will not have to use the memcpy in the runtime support library 
to resolve any references. Any modules that call memcpy that are not compiled 
with inlining enabled will generate calls that the linker resolves by getting the 
memcpy code out if the library. 

You will wantto use the JNLINE preprocessor symbol in the same way so that 
your programs will run regardless of whether inlining mode is selected for any 
or all of the modules in your program. 
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2.6 Using the Interlist Utility 

The compiler package includes a utility that interlists your original C source 
statements into the assembly language output of the compiler. The interlist 
utility enables you to inspect the assembly code generated for each C 
statement. 

The easiest way to invoke the interlist utility is to use the -ss shell option. To 
compile and run the interlist utility on a program called function.c, enter: 

cl30 -ss function 

2.6.1 Using the Interlist Utility Without the Optimizer 

The interlist utility runs as a separate pass between the code generator and 
the assembler. It reads both the assembly and C source files, merges them, 
and writes the C statements into the assembly file as comments surrounded 

by dashes, such as ;-. The output assembly file, function.asm, is 

assembled normally. The -ss option automatically prevents the cl30 shell from 
deleting the interlisted assembly language file (as if you had used -k). 

Example 2-2 shows a typical interlisted assembly file. 

Example 2-2. An Interlisted Assembly Language File 


-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'i t 

* FUNCTION NAME : _main * 

-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 

_main: 

r 

; 6 

main () 

r 

r 

; 8 

int i, j; 

r 

PUSH 

FP 


LDI 

SP, FP 


ADDI 

2, SP 

; io 

1 i 

+= j; 

r 

LDI 

*+FP(2),R0 


ADDI 

R0, *+FP(1),R1 


STI 

Rl, *+FP(l) 

; ii 

1 j 

= i + 123; 

r 

ADDI 

123,Rl 


STI 

Rl, *+FP(2) 
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2.6.2 Using the Interlist Utility With the Optimizer 

If the -os option is used with the optimizer (- 0 ), the interlist utility does not run 
as a separate pass. Instead, the optimizer inserts comments into the code indi¬ 
cating how the optimizer has rearranged and optimized the code. These com¬ 
ments appear in the assembly language file as comments starting with ; ***. 

Optimization makes normal source interlisting impractical because the 
optimizer extensively rearranges your program. Therefore, when you use the 
-os option, the optimizer writes reconstructed C statements. The comments 
also include a list of the allocated register variables. Note that occasionally the 
optimizer interlist comments may be misleading because of copy propagation 
or assignment of multiple or equivalent variables to the same register. 

If the -os option is specified and the optimizer (- 0 ) is not, the option will be 
ignored and the following warning will be issued: 

Optimizer comments requested, optimization not run, ignoring option -os 

If the -ss option is used with the optimizer (- 0 ), the original C source code is 
added to the assembly file by the interlist utility. In this case, to maintain a 
correspondence between the interlist comments and the code, optimization 
and instruction scheduling will take place on a line by line basis, roughly 
corresponding to the instructions between interlist comments. If both the -ss 
and -os options are used, the file generated contains the assembly code, the 
original C source comments, and the optimized source comments. 

The-s option will interlist optimizer comments into the assembly file if the com¬ 
ments are available; otherwise, it will use the interlist utility to interlist C source 
into the assembly file. 

To invoke the interlist utility outside of the shell, refer to subsection 2.9.4. 
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2.7 How the Compiler Handles Errors 

One of the compiler’s primary functions is to detect and report errors in the 
source program. When the compiler encounters an error in your program, it 
displays a message in the following format: 


’’file.c”, line n: [ECODE] error message 

“file.c” identifies the filename. 

line n: identifies the line number where the error occurs. 

[ECODE] is a 4-character error code. A single upper-case letter 

identifies the error class; a 3-digit number uniquely 
identifies the error. 

error message is the text of the message. 


Errors are divided into 4 classes according to severity; these classes are 
identified by the letters V/, E, F, and / (upper-case i). 


Code-W Error Messages 

Code-W errors are warnings. They result from a condition that is technically 
undefined according to the rules of the language, and code may not generate 
what you intended. This is an example of a code-W error: 

"file.c", line 42: [W063] illegal type for register variable 'x' 

Code-E Error Messages 

Code-E errors are recoverable. They result from a condition that violates the 
semantic rules of the language. Although these are normally fatal errors, the 
compiler can recover and generate an output file if you use the -pe option. 
Refer to subsection 2.7.1 for more information. This is an example of a 
code-E error: 

"file.c", line 66: [E056] illegal storage class for function 'f' 

Code-F Error Messages 

Code-F errors are fatal. They result from a condition that violates the syntactic 
or semantic rules of the language. The compiler cannot recover and therefore 
does not generate output for code-F errors. This is an example of a 
code-F error: 

"file.c", line 71: [F090] structure member 'a' undefined 
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Code-I Error Messages 

Code-I errors are implementation errors. They occur when one of the 
compiler’s internal limits is exceeded. These errors are usually caused by 
extreme behavior in the source code rather than by explicit errors. In most 
cases, code-l errors cause the compiler to abort immediately. Most 
code-l messages contain the maximum value for the limit that was exceeded. 
(Those limits that are absolute are also listed in Section 3.11 on page 3-24.) 
This is an example of a code-l error: 

"file.c", line 99: [1015] block nesting too deep (max=20) 


Other Error Messages 

The compiler also reports other errors, such as incorrect command line syntax 
or inability to find specified files.These errors are usually fatal and are identified 
by the symbol » preceding the message. 

This is an example of such an error: 

>> Cannot open source file 'mystery.c' 


2.7.1 Treating Code-E Errors as Warnings (-pe Option) 

A fatal error is an error that prevents the compiler from generating an output 
file. Normally, code-E, -F, and -I errors are fatal, while -W errors are not fatal. 
The -pe shell option causes the compiler to effectively treat code-E errors as 
warnings, so that the compiler will generate code for the file despite the error. 

Using -pe allows you to bend the rules of the language, so be careful. As with 
any warning, the compiler may not generate what you expect. 

Note that there is no way to specify recovery from code-F or -I errors; these 
are always fatal and prevent generation of a compiled output file. 

2.7.2 Suppressing Warning Messages (-pw Option) 

The -pw options inform the compiler to quietly ignore or to generate certain 
code-W messages (warnings). 

You can suppress all warning messages with the -pwO (or -pw) option. This 
can be useful when you are aware of the condition causing a warning and con¬ 
sider it innocuous. 
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The -pw2 option causes the compiler to report all warning messages, 
including messages that report undeclared functions at their point of call. 


2.7.3 An Example of How You Can Use Error Options 

The following example demonstrates how the -pe and -pw options can be 
used to suppress errors and error messages. The examples use this 2-line 
code segment: 

int *pi; char *pc; 
pi = pc; 

□ If you invoke the code with the shell (and -q), this is the result: 

[err] 

"err.c", line3: 

[E104] operands of '=' point to different types 

In this case, because code-E errors are fatal, the compiler does not 
generate code. 

□ If you invoke the code with the shell and the -pe option, this is the result: 

[err] 

"err.c", line3: 

[E104] operands of '=' point to different types 

In this case, the same message is generated, but because -pe is used, the 
compiler ignores the error and generates an output file. 

□ If you invoke the code with the shell and -pe and -pw, this is the result: 

[err] 

As in the previous case, -pe causes the compiler to overlook the error and 
generate code. Because the -pw option is used, the message is sup¬ 
pressed. 
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2.8 Intrinsics 


The compiler supports nine intrinsic functions: “built-in” functions whose 
bodies are supplied by the code generator. The supported intrinsics provide 
access to certain conversion and math instructions, as described in Table 2-3. 

Table 2-3. Supported Intrinsic Functions 


Function 

Description 

Processor(s) 

abs(i) 

Integer absolute value of i via ABSI 
instruction 

all 

labs(l) 

Long integer absolute value of 1 via ABSI 
instruction 

all 

fabs(f) 

Floating-point absolute value of f via ABSF 
instruction 

all 

toieee(f) 

Conversion of floating-point variable f to 
IEEE format via TOIEEE instruction 

C4x 

frieee(f) 

Conversion of IEEE formatted variable f to 
floating-point format via FRIEEE 
instruction 

C4x 

fast_ftoi(f) 

Conversion of floating-point variable f to 
integer via FIX instruction 

all 

ansi_ftoi(f) 

Conversion of floating-point variable f to 
integer using ANSI compatible conversion 
sequence 

all 

fastjmult(ij) 

24-bit integer multiplication of i and j using 
MPYI instruction (similar to specifying the 
-mm shell option) 

C3x 

fast_invf(f) 

16-bit floating-point inverse of f using 

RCPF instruction 

C4x 


When working with intrinsics, it is important to be aware of the following: 

□ If the -xO shell option is specified (disabling inline expansion), the compiler 
treats intrinsic functions as regular function calls. This means that, at link 
time, the linker will look for a function with the appropriate name and issue 
an error message if it has not been defined. It is your responsibility to pro¬ 
vide such a function. Note, however, that the runtime-support library 
includes callable functions for the abs, labs, and tabs intrinsics. 
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□ You should include the intrin.h file in any file that uses the intrinsics 
functions. 

□ The fast_ftoi intrinsic is similar to the -me shell option in that both cause 
the compiler to perform fast floating-point to integer conversions via the 
FIX instruction. However, the intrinsic gives you expression-by¬ 
expression control over this effect. The intrinsic performs the fast 
conversion whether or not the shell option is specified. 

□ The ansi_ftoi intrinsic causes the compiler to perform an ANSI-compatible 
floating-point to integer conversion via a standard sequence of 
instructions. The intrinsic gives you expression-by-expression control 
over this effect. Note that the ansi_ftoi intrinsic overrides the -me shell op¬ 
tion; the compiler will perform the ANSI-compatible conversion even if the 
-me shell option is specified. 

□ The fastjmult intrinsic is similar to the-mm shell option in that both cause 
the compiler to use 24-bit multiplication via the MPYI instruction. However, 
the intrinsic gives you expression-by-expression control over this effect. 
The intrinsic performs the 24-bit multiplication whether or not the shell 
option is specified. 

□ If the fastjnvf instrinsic is used, the compiler will use the 16-bit RCPF 
instruction rather than a 32-bit call to the INV F40 function. 
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2.9 Invoking the Tools Individually 

The TMS320C3x/C4x C compiler offers you the versatility of invoking all of the 
tools at once, using the shell, or invoking each of the tools individually. To 
satisfy a variety of applications, you can invoke the compiler (parser, optional 
optimizer, and code generator), the assembler, and the linker as individual pro¬ 
grams. This section also describes how to invoke the interlist utility outside the 
shell. 

Compiler 


The compiler is made up of three distinct programs: the parser, optimizer, and 
code generator. 

Figure 2-3. Compiler Overview 



The input for the parser is a C source file. The parser reads the source file, 
checking for syntax and semantic errors, and writes out an internal 
representation of the program called an intermediate file. Subsection 2.9.1, 
page 2-57, describes how to run the parser, and also describes how to run the 
parser in two passes: the first pass preprocesses the code, and the second 
pass parses the code. 

The optimizer is an optional pass that runs between the parser and the code 
generator. The input is the intermediate file (.if) produced by the parser. When 
you run the optimizer, you choose the level of optimization. The optimizer 
performs the optimizations on the intermediate file and produces a highly 
efficient version of the file in the same intermediate file format. Section 2.4, 
page 2-38, describes the optimizer. 

The input for the code generator is the intermediate file produced by the 
parser (.if) or the .opt file from the optimizer. The code generator produces an 
assembly language source file. Subsection 2.9.3, page 2-62, describes how 
to run the code generator. 


2-56 




































Invoking the Tools Individually 


Assembler 


The input for the assembler is the assembly language file produced by the 
code generator. The assembler produces a COFF object file. The assembler 
is described fully in the TMS320C3x/C4x Assembly Language Tools User’s 
Guide. 


Interlist Utility 


The inputs for the interlist utility are the assembly file produced by the compiler 
and the C source file. The utility produces an expanded assembly source file 
containing statements from the C file as assembly language comments. 
Section 2.6 on page 2-49 describes the interlisting file and subsection 2.9.4 
on page 2-64 describes the use of the interlist utility. 


Linker 


The input for the linker is the COFF object file produced by the assembler. The 
linker produces an executable object file. Section 2.10 describes how to run 
the linker. The linker is described fully in the TMS320C3x/C4x Assembly 
Language Tools User’s Guide. 


2.9.1 Invoking the Parser 


The first step in compiling a TMS320C3x/C4x C program is to invoke the C 
parser. The parser reads the source file, performs preprocessing functions, 
checks the syntax, and produces an intermediate file that can be used as input 
for the code generator. 

To invoke the parser, enter: 


ac30 input file [output file] [options] 


ac30 

input file 


is the command that invokes the parser. 


names the C source file that the parser uses as input. If 
you don’t supply an extension, the parser assumes that 
the file’s extension is .c. 


output file 


names the intermediate file that the parser creates. If you 
don’t supply a filename for the output file, the parser uses 
the input filename with an extension of .if. 


options 


affect parser operation. Each option available for the 
standalone parser has a corresponding shell option that 
performs the same function. Table 2-4 shows the shell 
options, the parser options, and the corresponding 
functions. 
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Table 2-4. Parser Options and Shell Options 


ac30 Option 

Shell Option 

Function 

-@name 

-@name 

causes the parser to read options from the 
specified file 

_? 

-p? 

enable trigraph expansion 

-d name [=def] 

-d name [=def] 

predefine macro name 

-e 

-pe 

treat code-E errors as warnings 

-f 

-pf 

prototype declared functions 

-i dir 

-i dir 

define #include search path 

-k 

-pk 

allow K&R compatibility 

-Iname 
(lowercase L) 

-plname 

generate .pp file 

-mb 

-mb 

use big memory model 

-mr 

-mr 

use register-argument runtime model 

-n 

-pn 

suppress #line directives 

-0 

-po 

preprocess only 

-p 

-pm 

compile all input modules into a single 
output module 

-q 

-q 

suppress progress messages (quiet) 

-r 

-pr 

write parser error messages to file 

-tt 

-tf 

relax prototype checking 

-tp 

-tp 

relax pointer combination 

-u name 

-u name 

undefine macro name 

-vxx 

-vxx 

select CPU version 

-wO (or -w) 

-pwO (or -pw) 

suppress all warning messages 

—wl 

-pwl 

enable serious warning messages 
(default) 

-w2 

-pw2 

enable all warning messages 

-xO 

-xO 

disable inline expansion 


—xl 

expand abs, tabs, and labs inline (default) 

-X 

-x or -x2 

#define JNLINE 
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Parsing in Two Passes 

Compiling very large source programs on small host systems such as PCs can 
cause the compiler to run out of memory and fail. You may be able to work 
around such host memory limitations by running the parser as two separate 
passes: the first pass preprocesses the file, and the second pass parses the 
file. 

When you run the parser as one pass, it uses host memory to store both macro 
definitions and symbol definitions simultaneously. But when you run the parser 
as two passes, these functions can be separated. The first pass performs only 
preprocessing, therefore memory is needed only for macro definitions. In the 
second pass, there are no macro definitions, therefore memory is needed only 
for the symbol table. 

The following example illustrates how to run the parser as two passes: 

1) Run the parser with the -po option, specifying preprocessing only. 

cl30 -po file.c 

If you want to use the -d, -mr, -u, -v, -x, or-i options, use them on this first 
pass. This pass produces a preprocessed output file called file.pp. For 
more information about the preprocessor, refer to Section 2.2. 

2) Rerun the whole compiler on the preprocessed file to finish compiling it. 

cl30 file.pp 

You can use any other options on this final pass. 

2.9.2 Optimizing Parser Output 

The second step in compiling a TMS320C3x/C4x C program — optimizing— 
is optional. After parsing a C source file, you can choose to process the 
intermediate file with the optimizer. The optimizer improves the execution 
speed and reduces the size of C programs. The optimizer reads the 
intermediate file, optimizes it according to the level you choose, and produces 
an intermediate file. The intermediate file has the same format as the original 
intermediate file, but it enables the code generator to produce more efficient 
code. 


C Compiler Description 


2-59 


Invoking the Tools Individually 


To invoke the optimizer, enter: 


opt30 [input file [output file ]] [options] 


opt30 

input file 

is the command that invokes the optimizer. 

names the intermediate file produced by the parser. The 
optimizer assumes that the extension is .if. 

output file 

names the intermediate file that the optimizer creates. If 
you don’t supply a filename for the output file, the 
optimizer uses the input filename with an extension of 
.opt. 

options 

affect the way the optimizer processes the input file. The 
options that you use in standalone optimization are the 
same as those used for the shell. Besides the optimizer 
options, some other compiler options may be used with 
the optimizer. Those formats are shown in Table 2-5. 
Section 2.4 provides a detailed list of the optimizations 
performed at each level. Detailed explanations of each 
optimizer option may be found on page 2-26. 
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Table 2-5. Optimizer Options and Shell Options 


opt30 Option 

Shell Option 

Function 

-a 

-ma 

assume variables are aliased 

-f 

-mf 

force indirect access to externals 

-hO 

-olO 

specify that this file alters a standard 
library function (-o3 only) 

-hi 

-oil 

specify that this file defines a standard 
library function (-o3 only) 

-h2 

—ol2 

specify that this file does not define or alter 
library functions (-o3 only) 

-i size 

-oi size 

set automatic inlining size (-o3 only) 

-k 

-pk 

allow K&R compatibility 

-m 

-mm 

enable short multiply (’C3x only) 

-nO 

-onO 

do not produce information file 

-nl 

-onl 

produce information file 

-n2 

-on2 

produce verbose information file 

-oO 

-oO 

level 0; register optimization 

—ol 

-ol 

level 1; level 0 + local optimization 

-o2 

-o2 

level 2; level 1 + global optimization 

-o3 

-o3 

level 3; level 2 + file optimization 

- P o 

-opO 

specify that callable functions and/or 
modifiable variables are used in this 
module 

-pi 

-opl 

specify that no callable functions are used 
in this module (default) 

-p2 

-op2 

specify that no modifiable variables or call¬ 
able functions are used in this module 

-p3 

-op3 

specify that no modifiable variables are 
used in this module, but modifiable func¬ 
tions may be used 

-q 

-q 

suppress progress messages (quiet) 

-r 

-mr 

use register-argument runtime model 

-s 

-os or -s 

interlist optimizer comments 

-u 

-ou 

allow zero-overhead loop operations 

-vxx 

-vxx 

specify processor; xx = 30, 31,32, 40, or 

44 (default is -v30) 

-z 


optimize primarily to reduce size, then to 
improve speed 
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2.9.3 Invoking the Code Generator 

The third step in compiling a TMS320C3x/C4x C program is to invoke the C 
code generator. As Figure 2-3 on page 2-56 shows, the code generator 
converts the intermediate file produced by the parser into an assembly 
language source file for input to the TMS320 floating-point assembler. You can 
modify this output file or use it as input for the assembler. The code generator 
produces re-entrant relocatable code, which, after assembling and linking, can 
be stored in ROM. 

To invoke the code generator as a standalone program, enter: 
cg30 [input file [output file [tempfile]]] [options] 


cg30 

input file 


output file 


tempfile 


options 


is the command that invokes the code generator. 

names the intermediate file that the code generator uses 
as input. If you don’t supply an extension, the code 
generator assumes that the extension is .if. If you don’t 
specify an input file, the code generator will prompt you 
for one. 

names the assembly language source file that the code 
generator creates. If you don’t supply a filename for the 
output file, the code generator uses the input filename 
with the extension of .asm. 

names a temporary file that the code generator creates 
and uses. The default filename for the temporary file is 
the input filename appended to an extension of .tmp. The 
code generator deletes this file after using it. 

affect the way the code generator processes the input 
file. Each option available for the standalone code 
generator mode has a corresponding shell option that 
performs the same function. The following table shows 
the shell options, the code generator options, and the 
corresponding functions. 
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Table 2-6. Code Generator Options and Shell Options 


cg30 Option 

Shell Option 

Function 

-gb 

-mb 

enable the big memory model 

-gc 

-me 

fast floating-point to integer conversions 

-gi 

-mi 

disables RPTS instructions for loops (uses 

RPTB) 

-gi 

-ml 

use far calls for runtime support assembly calls 

-gm 

-mm 

enable short multiply (’C3x only) 

-gn 

-mn 

re-enable optimizations disabled by symbolic 
debugging 

-gp 

-mp 

perform speed optimizations at the cost of code 
size 

-grO 


use standard (stack) runtime model 

-grl (or-gr) 

-mr 

use register-argument runtime model 

-gs 

-ms 

assume all memory is accessible when optimiz¬ 
ing 

-gsrev# 


specify silicon revision (see -msrev in shell) 

-gt 

-mt 

generate Ada compatible frame structure 

-gtc 

-mtc 

generate Tartan C function names 

-n 

-0 -s 

perform optimizations while generating interlist 
information 

-0 

-g 

enable symbolic debugging 

-q 

-q 

suppress progress messages (quiet) 

—V XX 

-vxx 

specify processor; xx = 30, 31,32, 40, or 44 
(default is -v30) 

-z 


retain the input file 


t -z tells the code generator to retain the input file (the intermediate file created by the parser). 
This option is useful for creating several output files with different options; for example, you might 
want to use the same intermediate file to create one file that contains symbolic debugging 
directives (-0 option) and one that doesn’t. Note that if you do not specify the -z option, the code 
generator deletes the input (intermediate) file. 
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2.9.4 Invoking the Interlist Utility 

The fourth step in compiling a TMS320C3x/C4x C program is optional. After 
you have compiled a program, you can run the interlist utility. To run the interlist 
utility from the command line, the syntax is: 

clist asmfile [outfile] [-options] 


clist is the command that invokes the interlist utility. 

asmfile is the filename of assembly language output from the compiler. 

outfile names the interlisted output file. If you omit this, the file has the 
same name as the assembly file with an extension .cl. 

options control the operation of the utility as follows: 

-b removes blanks and useless lines (lines containing 
comments or lines containing only { or }). 

-r removes symbolic debugging directives. 

-q suppresses banner and status information. 

The interlist utility uses .line directives, produced by the code generator, to 
associate assembly code with C source. For this reason, when you compile 
the program, you must use the -g shell option to specify symbolic debugging 
if you want to interlist it. If you do not want the debugging directives in the 
output, use the -r interlist option to remove them from the interlisted file. 

The following example shows how to compile and interlist function.c. To 
compile, enter: 

cl30 -gk -inn function 

This compiles and produces symbolic debugging directives, keeps the 
assembly language file, and allows normal optimization. 

To produce an interlist file, enter 

clist -r function 

This interlists and removes debugging directives from the file. The output from 
this example is function.cl. 
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2.10 Linking C Code 

The TMS320C3x/C4x C compiler and assembly language tools provide two 
methods for linking your programs: 

□ you can link object files using the linker alone. 

□ you can compile, assemble, and link in one step by using the shell. This 
is useful when you have a single source module. 

This section describes how to invoke the linker with each method. It also 
discusses special requirements of linking C code: including the 
runtime-support libraries, specifying the initialization model, and allocating the 
program into memory. 


2.10.1 Invoking the Linker 

The TMS320C3x/C4x C compiler and assembly language tools support 
modular programming by allowing you to compile and assemble individual 
modules and then link them together. 

The general syntax for invoking the linker is: 

Ink30 [-options] filename y ... fiiename n 


Ink30 is the command that invokes the linker. 

options can appear anywhere on the command line or in a linker 
command file. (Options are discussed in Table 2-1, page 
2 - 6 .) 

filenames can be object files, linker command files, or archive libraries. 

The default extension for all input files is . obj ; any other 
extension must be explicitly specified. The linker can deter¬ 
mine whether the input file is an object file or an ASCII file that 
contains linker commands. The default output filename is 
a.out. 


Linker options can be specified on the command line or in a command file. The 
command file allows you to use the MEMORY and SECTIONS directives, 
which can customize your memory to your specifications. If you enter the Ink30 
command with no options, the linker will prompt for them. 

Command files : 

Object files [.obj] : 

Output files [ ] : 

Options : 
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This is the usual syntax for linking compiler-based C programs as a separate 
step: 


Ink30 -c filenames 

-o name, out 

-1 rts.lib 

or 



Ink30 -cr filenames 

-o name, out 

-1 rts.lib 


Ink30 is the command that invokes the linker. 


-c/-cr 


filenames 
-o name, out 
-i rts.lib 


are options that tell the linker to use special conventions 
defined by the C environment. Note that when you use the 
shell to link, it automatically passes -c to the linker. 

are object files created by compiling and assembling C 
programs. 

names the output file. If you don’t use the -o option, the link¬ 
er creates an output file with the default name of a.out. 

identifies the appropriate archive library containing C 
runtime-support and floating-point math functions. 
(The -I option tells the linker that a file is an object library.) 
If you’re linking C code, you must use a runtime-support 
library. The rts.lib library is included with the C compiler. 


Whenever you specify a library as linker input, the linker includes and links only 
those library members that resolve undefined references. For example, you 
can link a C program consisting of modules progl, prog2, and prog3 
(the output file is named prog.out): 

lnk30 -c progl prog2 prog3 -1 rts30.1ib -o prog.out 

The linker uses a default allocation algorithm to allocate your program into 
memory. You can use the MEMORY and SECTIONS linker directives to 
customize the allocation process, and you can also use other linker options, 
described in Table 2-1 on page 2-6. These directives are also described in 
Chapter 8 of the TMS320C3x/C4x Assembly Language Tools User’s Guide. 


2.10.2 Using the Shell to Invoke the Linker (-z Option) 

The options and parameters discussed in this section apply to both methods 
of linking; however,when you are linking with the shell, the options follow the 
-z shell option. 

By default, the shell does not run the linker. However, if you use the -z option, 
the shell compiles, assembles, and links in one step. When using -z to enable 
linking, remember that: 

□ -z must follow all source files and compiler options on the command line 
(or be specified with C_OPTION) 
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□ -z divides the command line into compiler options (before -z) and linker 
options (following -z) 

□ -c and -n suppress -z, so do not use them if you want to link 

For all arguments that follow -z on the command line, the shell generates a 
linker command file containing the arguments. The shell passes the command 
file to the linker. In this way, you are not limited by command line size restric¬ 
tions. The arguments can be other linker command files, object files, linker op¬ 
tions, or libraries. For example, to compile and link all the .c files in a directory, 
enter: 

cl30 -sq *.c -z c.cmd -o prog.out -1 rts30.1ib 

The shell will call the compiler using the -s and -q options to compile all of the 
files in the current directory that end with a .c extension. Because -z is 
specified, the shell will generate a command file containing all of the argu¬ 
ments following the -z option and then invoke the linker with this command file. 
The linker will link together all of the object files produced during compilation, 
the runtime support library, and any additional files specified in c.cmd. The 
resulting linked file will be named prog.out. 

The order in which the linker processes arguments can be important, 
especially for command files and libraries. The cl30 shell passes arguments 
to the linker in the following order: 

1) Object file names from the command line 

2) Arguments following -z on the command line 

3) Arguments following -z from the C_OPTION environment variable 

-c and -n Shell Options 

You can override the -z option by using the -c or -n shell options. The 
-c option is especially helpful when you have specified -z in the C_OPTION 
environment variable and want to selectively disable linking with -c on the 
command line. The -n option causes the shell to stop the process after com¬ 
pilation. 

The -c linker option has a different function than, and is independent of, the 
-c shell option. By default, the shell automatically uses the-c linker option that 
tells the linker to use C linking conventions (ROM model of initialization). If you 
want to use -cr (RAM model of initialization) rather than -c, you can pass -cr 
as a linker option instead. 
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2.10.3 Controlling the Linking Process 

Regardless of the method you choose for invoking the linker, special 
requirements apply when linking C programs. You must: 

□ include the compiler’s runtime-support library 

□ specify the initialization model 

□ determine how you want to allocate your program into memory 

This section discusses how these factors are controlled and provides an 
example of the standard default linker command file. 

For more information about how to operate the linker, refer to Chapter 8 of the 
TMS320C3x/C4x Assembly Language Tools User’s Guide. 


Runtime-Support Libraries 

All C programs must be linked with a runtime-support library. This archive 
library contains standard C library functions (such as malloc and strcpy) as well 
as functions used by the compiler to manage the C environment. To link a 
library, simply use the -I option on the command line: 

lnk30 -c filenames -1 rts30.1ib -1 flib30.1ib ... or 

lnk30 -cr filenames -1 rts30.1ib -1 flib30.1ib ... 

Eight versions of the standard C runtime-support libraries are included with the 
compiler. Refer to section 2.3 for further information on the included runtime 
support libraries. 

Generally, the libraries should be specified as the last filename on the command 
line because the linker searches libraries for unresolved references in the order 
that files are specified on the command line. If any object files follow a library, 
references from those object files to that library will not be resolved. You can 
use the -x option to force the linker to reread all libraries until references are 
resolved. Whenever you specify a library as linker input, the linker includes and 
links only those library member that resolve undefined references. 

All C programs must be linked with an object module called boot.obj. When a 
program begins running, it executes boot.obj first, boot.obj contains code and 
data for initializing the runtime environment; the linker automatically extracts 
boot.obj and links it when you use -c or -cr and include rts.lib in the link. 
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Initialization (RAM and ROM Models) 

The C compiler produces tables of data for autoinitializing global variables. 
The format of these tables is discussed on page 4-37. These tables are in a 
named section called .cinit. The initialization tables can be used in either of two 
ways: 

□ RAM Model (-cr linker option) 

Global variables are initialized at load time. Use the -cr linker option to 
select the RAM model. For more information about the RAM model, refer 
to page 4-38. 

□ ROM Model (-c linker option) 

Global variables are initialized at runtime. Use the -c linker option to select 
the ROM model. For more information about the ROM model, refer to page 
4-37. 


The -c and -cr Linker Options 

Whenever you link a C program, you must use either the -c or the -cr option. 
These options tell the linker to use special conventions required by the 
C environment; for example, they tell the linker to select the ROM or RAM 
model of autoinitialization. Note that when you use the shell to link programs, 
the -c option is the default. The following list outlines the linking conventions 
used with -c or -cr: 

□ The symbol _c_int00 is defined as the program entry point; it identifies the 
beginning of the C boot routine in boot.obj. When you use -c or -cr, 
_cjnt00 is automatically referenced; this ensures that boot.obj is auto¬ 
matically linked in from the runtime-support library used. 

□ The .cinit output section is padded with a termination record so that the 
loader (RAM model) or the boot routine (ROM model) knows when to stop 
reading the initialization tables. 

□ In the RAM model (-cr option), 

■ The linker sets the symbol cinit to -1. This indicates that the 
initialization tables are not in memory, so no initialization is performed 
at runtime. 
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■ The STYP_COPY flag (01 Oh) is set in the .cinit section header. 
STYP_COPY is the special attribute that tells the loader to perform 
autoinitialization directly and not to load the .cinit section into memory. 
The linker does not allocate space in memory for the .cinit section. 

Note that a loader is not included as part of the C compiler package. 

□ In the ROM model (-c option), the linker defines the symbol cinit as the 
starting address of the .cinit section. The C boot routine uses this symbol 
as the starting point for autoinitialization. 

Sections Created by the Compiler 

The compiler produces five relocatable blocks of code and data. These blocks, 
called sections, can be allocated into memory in a variety of ways to conform 
to a variety of system configurations. 

The compiler creates two basic kinds of sections: initialized and uninitialized. 
Table 2-7 summarizes the sections. 

Table 2-7. Sections Created by the Compiler 


Name 

Type 

Contents 

.bss 

Uninitialized 

global and static variables 

.cinit 

Initialized 

initialization values for explicitly initialized global and 
static variables 

.const 

Initialized 

global and static constant variables that are explicitly 
initialized and string literals 

.stack 

Uninitialized 

software stack 

.text 

Initialized 

executable code and floating-point constant 

.sysmem 

Uninitialized 

memory for malloc functions 


When you link your program, you must specify where to locate the sections in 
memory. In general, initialized sections can be linked into ROM or RAM; 
uninitialized sections must be linked into RAM. Refer to subsection 4.1.1 on 
page 4-2 for a complete description of how the compiler uses these sections. 
The linker provides MEMORY and SECTIONS directives for performing this 
process. 

For more information about allocating sections into memory, refer to 
Chapter 9, in the TMS320C3x/C4x Assembly Language Tools User’s Guide. 

Sizing the Stack and Heap 

The linker provides four options that allow you to specify the size of the .stack 
and .sysmem sections. 
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-stackxxxx sets the size of the .stack section to xxxxwords. The value xxxx 
must be constant. 

-heapxxxx sets the size of the .sysmem section to xxxxwords. The value 
xxxx must be constant. 

-heap8xxxx sets the size of the .sysm8 section to xxxxwords (for C32 8-bit 
memory support). The value of xxxx must be constant. 

-heap16xxxx 

sets the size of the .sysml 6 section to xxxxwords (for C32 16-bit 
memory support). The value of xxxx must be constant. 

The linker always includes the stack section; and includes the .sysmem, 
.sysm8, or .sysml 6 sections only if you use memory allocation functions (such 
as malloc(), malloc8(), or malloc16()). The default size for all sections is IK 
(1024) words. Note, however, that the .sysm8 and .sysml 6 sections are not 
created unless the 8-bit or 16-bit memory support functions are linked. 

Allocating the .bss and .const Section 

When you use the small memory (default) model, the sum of the entire .bss 
and .const section must fit within a single 64K word long data page and must 
not cross any 64K address boundaries. Use the linker’s block qualifier to help 
guarantee the correct allocation of .bss and .const. 

Sample Linker Command File 

The compiler package includes two sample linker command files called 
c30.cmd and c40.cmd that can be used to link C programs. To link your 
program using a command file, enter the following command: 

lnk30 object.files -o output.file -m map. file c30.cmd 

Figure 2-4 shows the contents of c30.cmd. Figure 2-5 shows the contents of 
c40.cmd. 

To link your program using the TMS320C4x command file, enter the following 
command: 

lnk30 object.files -o output.file -m map. file c40.cmd 
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Figure 2-4. Sample Linker Command File for TMS320C3x C Programs 


/****************************************************************************/ 

/* C30 

. CMD - 

v4 . 

60 COMMAND FILE FOR LINKING C30 C PROGRAMS 

*/ 

/* 




*/ 

/* 

Usage: 


lnk30 <obj files...> -o <out file> -m <map file> c30.cmd 

*/ 

/* 




*/ 

/* 

Description 

: This file is a sample command file that can be used 

*/ 

/* 



for linking programs built with the TMS320C30 C 

*/ 

/* 



Compiler. Use it a guideline; you may want to change 

*/ 

/* 



the allocation scheme according to the size of your 

*/ 

/* 



program and the memory layout of your target system. 

*/ 

/* 




*/ 

/* 

Notes: 

(1) 

Be sure to use the right library! Use a library that 

*/ 

/* 



matches the runtime model you are using. 

*/ 

/* 




*/ 

/* 


(2) 

You must specify the directory in which rts.lib is 

*/ 

/* 



located. Either add a "-i<directory>" line to this 

*/ 

/* 



file, or use the system environment variable C_DIR to 

*/ 

/* 



specify a search path for libraries. 

*/ 

/* 




*/ 

/* 


(3) 

When using the small (default) memory model, be sure 

*/ 

/* 



that the ENTIRE .bss section fits within a single page. 

*/ 

/* 



To satisfy this, .bss must be smaller than 64K words and 

*/ 

/* 



must not cross any 64K boundaries. 

*/ 

/************************************************************^**** 

-c 



/* LINK USING C CONVENTIONS * 

7 

-stack 

0x400 


/* IK STACK 

*/ 

-heap 

0x400 


/* IK HEAP 

*/ 

-lrts30.lib 


/* GET RUN-TIME SUPPORT 

*/ 


/* SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 

{ 


ROM: 

org = 

0x0 

len = 

0x1000 

/* 

INTERNAL 

4K ROM 

*/ 

EXT0 : 

org = 

0x1000 

len = 

0x7ff000 

/* 

EXTERNAL 

MEMORY 

*/ 

XBUS : 

org = 

0x800000 

len = 

0x2000 

/* 

EXPANSION 

BUS 

* / 

IOBUS: 

org = 

0x804000 

len = 

0x2000 

/* 

I/O BUS 


* / 

RAM0 : 

org = 

0x809800 

len = 

0x400 

/* 

RAM BLOCK 

0 

*/ 

RAMI: 

org = 

0x809c00 

len = 

0x400 

/* 

RAM BLOCK 

1 

*/ 

EXT1 : 

org = 

0x80a000 

len = 

0x7f6000 

/* 

EXTERNAL 

MEMORY 

*/ 


} 

/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 

SECTIONS 

{ 


text: 

> 

EXT0 

/* 

CODE 


*/ 

cinit: 

> 

EXT0 

/* 

INITIALIZATION 

TABLES 

*/ 

const: 

> 

EXT0 

/* 

CONSTANTS 


*/ 

stack: 

> 

RAM0 

/* 

SYSTEM STACK 


*/ 

sysmem: 

> 

RAMI 

/* 

DYNAMIC MEMORY 

(HEAP) 

*/ 

bss : 

> 

EXT1, block 0x10000 

/* 

VARIABLES 


*/ 


} 


2-72 




Linking C Code 


Figure 2-5. Sample Linker Command File for TMS320C4x C Programs 


/****************************************************************************/ 

/* 

C40.CMD - 

v4 . 

60 COMMAND FILE FOR LINKING C40 C PROGRAMS 

*/ 

/* 




*/ 

/* 

Usage: 


lnk30 <obj files...> -o <out file> -m <map file> c40.cmd 

*/ 

/* 




*/ 

/* 

Description 

: This file is a sample command file that can be used 

*/ 

/* 



for linking programs built with the TMS320C40 C 

*/ 

/* 



Compiler. Use it a guideline; you may want to change 

*/ 

/* 



the allocation scheme according to the size of your 

*/ 

/* 



program and the memory layout of your target system. 

*/ 

/* 




*/ 

/* 

Notes: 

(1) 

Be sure to use the right library! Use a library that 

*/ 

/* 



matches the runtime model you are using. 

*/ 

/* 




*/ 

/* 


(2) 

You must specify the directory in which rts.lib is 

*/ 

/* 



located. Either add a "-i<directory>" line to this 

*/ 

/* 



file, or use the system environment variable C_DIR to 

*/ 

/* 



specify a search path for libraries. 

*/ 

/* 




*/ 

/* 


(3) 

When using the small (default) memory model, be sure 

*/ 

/* 



that the ENTIRE .bss section fits within a single page. 

*/ 

/* 



To satisfy this, .bss must be smaller than 64K words and 

*/ 

/* 



must not cross any 64K boundaries. 

*/ 


-c 



/* LINK USING C CONVENTIONS 

*/ 

-stack 0x400 


/* IK STACK 

*/ 

-heap 0x400 


/* IK HEAP 

*/ 

-lrts4 0.lib 


/* GET RUN-TIME SUPPORT 

*/ 

/* 

SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 





ROM: 

org = 

0x000000 

len = 

0x1000 

/* 

INTERNAL ROM 

*/ 

RAM0 : 

org = 

0x2FF800 

len = 

0x400 

/* 

RAM BLOCK 0 

*/ 

RAMI : 

org = 

0x2FFC00 

len = 

0x400 

/* 

RAM BLOCK 1 

*/ 

LOCAL: 

org = 

0x300000 

len = 

0x7D00000 

/* 

LOCAL BUS 

*/ 

GLOBAL: 

org = 

0x8000000 

len = 

0x8000000 

/* 

GLOBAL BUS 

*/ 


} 

/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 

SECTIONS 

{ 


text: 

> 

LOCAL 

/* 

CODE 


*/ 

cinit: 

> 

LOCAL 

/* 

INITIALIZATION 

TABLES 

*/ 

const: 

> 

LOCAL 

/* 

CONSTANTS 


*/ 

stack: 

> 

RAM0 

/* 

SYSTEM STACK 


*/ 

sysmem: 

> 

RAMI 

/* 

DYNAMIC MEMORY 

(HEAP) 

*/ 

bss : 

> 

LOCAL, block 0x10000 

/* 

VARIABLES 


*/ 


} 
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In these command files, the -c option specifies that the linker use the ROM 
initialization model, and the -I (lowercase “L”) option with rts30.lib (or any of 
the runtime support libraries) specifies that the linker search for the library 
named. If the library is not in the current directory, you can customize the 
command file to use C_DIR or the -i option to define a path where the rts.lib 
can be found. 

You will most likely have to customize the command file to fit a particular 
application by adding or modifying options, libraries, memory configurations, 
and section allocations. If you use the RAM initialization model, change -c to 
-cr. If you use the big memory model, you can remove the 64K-word blocking 
on the .bss section. 

For more information about operating the linker, refer to the linker chapter in 
the TMS320C3x/C4x Assembly Language Tools User’s Guide. 
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TMS320C3x/C4x C Language 


The TMS320C3x/C4x C compiler supports the C language based on the ANSI 
(American National Standards Institute) C standard. This standard was 
developed by a committee chartered by ANSI to standardize the C program¬ 
ming language. 

ANSI C supersedes the de facto C standard, which was described in the first 
edition of The C Programming Language and based on the UNIX System V 
C language. The ANSI standard is described in the American National 
Standard for Information Systems-Programming Language C X3.159-1989. 
The second edition of The C Programming Language, by Kernighan and 
Ritchie, is based on the ANSI standard and is used here as a reference. ANSI 
C encompasses many of the language extensions provided by recent C com¬ 
pilers and formalizes many previously unspecified characteristics of the 
language. 

The TMS320C3x/C4x C compiler strictly conforms to the ANSI C standard. 
The ANSI standard identifies certain implementation-defined features that 
may differ from compiler to compiler, depending on the type of processor, the 
runtime environment, and the host environment. This chapter describes how 
these and other features are implemented for the TMS320C3x/C4x C 
compiler. These are the topics covered in this chapter: 


Topic 


Page 


3.1 

3.2 


3.3 

3.4 


3.5 


3.6 

3.7 

3.8 


3.9 

3.10 

3.11 


Characteristics of TMS320C3x/C4x C . 

Data Types . 

Keywords . 

Register Variables. 

Pragma Directives . 

The asm Statement. 

Initializing Static and Global Variables 

Far Call Support . 

Delay Slot Filling for Branches. 

Compatibility with K&R C (-pk Option) 
Compiler Limits. 


EH 

2d 
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Characteristics of TMS320C3x/C4x C 


3.1 Characteristics of TMS320C3x/C4x C 

The ANSI standard identifies some features of the C language that are af¬ 
fected by characteristics of the target processor, runtime environment, or host 
environment. For reasons of efficiency or practicality, this set of features may 
differ among standard compilers. This section describes how these features 
are implemented for the TMS320C3x/C4x C compiler. 

The following list identifies all such cases and describes the behavior of the 
TMS320C3x/C4x C compiler in each case. Each description also includes a 
reference to the formal ANSI standard and to the The C Programming 
Language by Kernighan and Ritchie (K&R). 


Identifiers and constants 

□ The first 100 characters of all identifiers are significant. Case is significant; 

uppercase and lowercase characters are distinct for identifiers. These 
characteristics apply to all identifiers, internal and external, in all 
TMS320C3x/C4x tools. (ANSI 3.1.2, K&R A2.3) 

□ The source (host) and execution (target) character sets are assumed to 
be ASCII. Although the compiler recognizes the syntax of multibyte 
characters, there are no additional multibyte characters. 

(ANSI 2.2.1, K&R A12.1) 

□ Hex or octal escape sequences in character or string constants may have 

values up to 32 bits. (ANSI 3.1.3.4, K&R A2.5.2) 

□ Character constants with multiple characters are encoded as the last 
character in the sequence. For example, 

'abc' == ' c' (ANSI 3.1.3.4, K&R A2.5.2) 

Data types 

□ For information about the representation of data types, refer to Section 

3.2. (ANSI 3.1.2.5, K&R A4.2) 

□ The type size_t, which is assigned to the result of the sizeof operator, is 

equivalent to unsigned int. (ANSI 3.3.3.4, K&R A7.4.8) 

□ The type ptrdiff_t, which is assigned to the result of pointer subtraction, is 

equivalent to int. (ANSI 3.3.6, K&R A7.7) 
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Conversions 

□ Int-to-float conversions use the TMS320C3x/C4x FLOAT instruction 
which produces an exact representation. However, the value may be trun¬ 
cated when written to memory, resulting in a loss of precision towards 
negative infinity. 

(ANSI 3.2.1.3, K&R A6.3) 

□ Pointers and integers can be freely converted. 

(ANSI 3.3.4, K&R A6.6) 

Expressions 

□ When two signed integers are divided and either is negative, the quotient 
is negative. A signed modulus operation takes the sign of the dividend (the 
first operand). For example, 

10 / -3 == -3, -10 / 3 == -3 

10 % -3 == l, -10 % 3 == -l (ANSI 3.3.5, K&R A7.6) 

□ A right shift of a signed value is an arithmetic shift; that is, the sign is pre¬ 
served. (ANSI 3.3.7, K&R A7.8) 

Declarations 

□ The register storage class is effective for all character, short, integer, and 

pointer types. (ANSI 3.5.1, K&R A8.1) 

□ Structure members are not packed into words (with the exception of bit 
fields). Each member is aligned on a 32-bit word boundary. 

(ANSI 3.5.2.1, K&R A8.3) 

□ A bit field of type integer is signed. Bit fields are packed into words, begin¬ 
ning at the low-order bits, and do not cross word boundaries. 

(ANSI 3.5.2.1, K&R A8.3) 

Preprocessor 

□ The preprocessor recognizes one #pragma directive; all others are ig¬ 
nored. For details, see Section 3.5, Pragma Directives. The recognized 
pragma is: 

#pragma DATA_SECTION ( symbol, ” section name”) 

□ The standard #error preprocessor directive forces the compiler to issue a 
diagnostic message and halt compilation. The TMS320C3x/C4x compiler 
extends the #error directive with a #warn directive, which, like #error, 
forces a diagnostic message but does not halt compilation. The syntax of 
#warn is identical to #error. 

(K&R A12.7) 
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3.2 Data Types 


□ All integer types (char, short, int, long, and their unsigned counterparts) 
are equivalent types and are represented as 32-bit binary values. 

□ Signed types are represented in 2s-complement notation. 

□ The type char is a signed type, equivalent to int. 

□ Objects of type enum are represented as 32-bit values; in expressions, the 
type enum is equivalent to int. 

□ Floating-point types float and double are equivalent and are represented 
in the TMS320C3x/C4x 32-bit single-precision floating-point format. 

□ Floating-point type long double is represented in the TMS320C3x/C4x 
40-bit extended-precision format. 

□ Although floating-point types are not directly supported, support is pro¬ 
vided for conversion to and from IEEE single and double-precision format 
for the TMS320C4x processors through the assembly language functions 
TOIEEE and FRIEEE. See the TMS320C4x User’s Guide tor more infor¬ 
mation on these instructions. 

The size, representation, and range of each scalar data type are listed in the 

table below. 


Table 3-1. TMS320C3x/C4x C Data Types 


Type 

Size 

Representation 

Range 

Minimum Maximum 

char, signed char 

32 

bits 

ASCII 

-2147483648 

2147483647 

unsigned char 

32 

bits 

ASCII 

0 

4294967295 

short 

32 

bits 

2s complement 

-2147483648 

2147483647 

unsigned char 

32 

bits 

binary 

0 

4294967295 

int, signed int 

32 

bits 

2s complement 

-2147483648 

2147483647 

unsigned int 

32 

bits 

binary 

0 

4294967295 

long, signed long 

32 

bits 

2s complement 

-2147483648 

2147483647 

unsigned long 

32 

bits 

binary 

0 

4294967295 

enum 

32 

bits 

2s complement 

-2147483648 

2147483647 

float 

32 

bits 

TMS320C3x/C4x 

5.877472e-39 

3.4028235e38 

double 

32 

bits 

TMS320C3x/C4x 

5.877472e-39 

3.4028235e38 

long double 

40 

bits 

TMS320C3x/C4x 

5.87747175e-: 

39 

3.4028236684e38 

pointers 

32 

bits 

binary 

0 

OxFFFFFFFF 


3-4 





Data Types 


Many of the range values are available as standard macros in the header file 
limits.h, which is supplied with the compiler. 

I-1 

Note: A TMS320C3x/C4x Byte Is 32 Bits 

The ANSI definition specifies that the sizeof operator yields the number of 
bytes required to store an object. ANSI further stipulates that when the 
sizeof operator is applied to type char, the result is one. Since the 
TMS320C3x/C4x char is 32 bits (to make it separately addressable), a byte 
is also 32 bits. This yields results that you may not expect; for example, 
sizeof (int) == 1 (not 4). TMS320C3x/C4x bytes and words are equivalent (32 
bits). 

I_I 


3.2.1 The Long Double Data Type 

The long double data type is handled differently than the other floating-point 

data types. The features of long doubles are described below: 

□ Long doubles are not represented in the single-precision 32-bit format 
used for floats and doubles, but in extended-precision 40-bit format. 

□ Long doubles require two memory words for storage; the first word con¬ 
tains the upper 24 bits and the second word contains the lower 24 bits. 

The sizeof(long double) operator returns 2. 

Two instructions are required to load and/or store long doubles. 

□ Long doubles can be stored in one floating-point register and, like floats 
and doubles, can be passed as parameters in registers. 

□ No register variable can hold a 40-bit value; therefore, a long double can¬ 
not be held in a register variable across a call. It will be stored to memory 
before the call and then reloaded when needed. 

□ In float/double to long double conversion, the lower 8 bits of the 40-bit 
register will be filled with zeros. In long double to float/double conversion, 
the value will be rounded to the nearest single-precision floating-point 
value using the RND instruction. 
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□ Addition, subtraction, and negation use assembly instructions when the 
instructions are able to accept extended-precision floating-point values as 
input. 

’C3x multiplication uses the runtime-support assembly function MPY_LD; 
’C4x multiplication uses the MPYF instruction. 

Inversion and reciprocals use the runtime-support assembly function 
INV_LD. 

Division uses the runtime-support assembly function DIV_LD. 

□ The 40-bit runtime-support assembly functions are linked into their own 
section called .float40. 
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3.3 Keywords 

3.3.1 The cregister Keyword 

The TMS320C3x/C4x compiler extends the C language by adding the cregis¬ 
ter keyword to allow high level language access to control registers. 

When you use the cregister keyword on an object, the compiler compares the 
name of the ojbect to a list of standard control registers for the ’C3x/C4x (see 
Table 3-2). If the name matches, the compiler generates the code to reference 
the control register. If the name does not match, the compiler issues an error. 

Table 3-2. Valid Control Registers 


Register 

Description 

IE 

CPU/DMS interrupt enable register 

IF 

CPU interrupt flag register 

IOF 

I/O flags 

ST 

Status register 


The cregister keyword can only be used in file scope. The cregister keyword 
is not allowed on any declaration within the boundaries of a function. It can only 
be used on objects of type integer or pointer. The cregister keyword is not al¬ 
lowed on objects of any floating-point type or on any structure or union object. 

The cregister keyword does not imply that the object is volatile. If the control 
register being referenced is volatile (that is, can be modified by some external 
control), then the object should be declared with the volatile keyword also. 

To use a control register in Table 3-2, you must declare each register (with or 
without volatile) as follows: 

extern cregsiter volatile unsigned int register; 

Once you have declared the register, you can use the register name directly. 
See TMS320C3x/C4x CPU and Instruction Set Reference Guide for detailed 
information on the control registers. 
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Example 3-1. Define and Use Control Registers 


extern 

cregisger 

volatile 

unsigned 

int 

IE; 

extern 

cregister 

volatile 

unsigned 

int 

IF; 

extern 

cregisger 

volatile 

unsigned 

int 

IOF; 

extern 

cregister 

volatile 

unsigned 

int 

ST; 

unsigned myfunc 

/ 

(unsigned 

int mask) 




while (ST 

& mask == 

0) 




. /* 

Do nothing; wait 

*7; 


} 

return IOF; 





3.3.2 The near and far Keywords 

The ’C3x/C4x C compiler extends the C language with the near and far key¬ 
words to specify how global and static variables are accessed and how func¬ 
tions are called. 

Syntactically, the near and far keywords are treated as storage class modifiers. 
They can appear before, after, or in between the storage class specifiers and 
types. Two storage class modifiers cannot be used together in a single decla¬ 
ration. For example: 

far static int x; 
static near int x; 
static int far x; 
far int foo (); 
static far int foo () 


Near and far data objects 

Global and static data objects can be accessed in the following two ways: 

near keyword The compiler assumes that the data item can be accessed 
relative to the data page pointer. For example: 

sti ro, @_var 

far keyword The compiler cannot access the data item via the dp. This 
can be required if the total amount of program data is larger 
than the offset allowed (32K) from the DP. For example: 

ldiu @cll, aro 
sti ro, *aro 

where ell in the .bss holds the address of the variable. 
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By default, the compiler generates small-memory model code, which means 
that every data object is handled as if it were declared near, unless it is actually 
declared far. If an object is declared near, it is normally loaded using relative 
offset addressing from the data page pointer (DP, which is B14). DP points to 
the beginning of the .bss section. If the options -ml, -mb, and -mf are used, 
the default assumptions change. Large-memory model code, which means 
that every data object is handled as if it were declared far, is then generated. 

If you use the DATA_SECTION pragma, the object is indicated as a far vari¬ 
able, and this cannot be overridden. This ensures access to the variable, since 
the variable might not be on the same data page as the .bss section. See sec¬ 
tion 3.5.2, The DATA_SECTIONpragma, on page 3-13. 

Near and far function calls 

Function calls can be invoked in one of two ways: 

near keyword The compiler assumes that the destination of the call is 
within 2 24 bytes of the caller. Here, the compiler uses the 
PC-relative call instruction. 

call _func 

far keyword The compiler is told by the user that the call is not within 2 24 
bytes of the caller, and the compiler uses the register ad¬ 
dressing mode of the call instruction. 

ldiu @cll, ro 
callu ro 


where constant ell in the .bss holds the address of the function. 

By default, the compiler generates small-memory model code, which means 
that every function call is handled as if it were declared near, unless it is actu¬ 
ally declared far. The default changes, however, when options -ml, -mf, and 
-mb are used. Large-memory model code, which means that every data ob¬ 
ject is handled as if it were declared far, is then generated. 
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3.4 Register Variables 

The TMS320C3x/C4x C compiler treats register variables (variables declared 
with the register keyword) differently, depending on whether or not you use the 
optimizer. 

Compiling With the Optimizer 

The compiler ignores any register declarations and treats all variables as 
register variables while optimizing. 

Compiling Without the Optimizer 

If you use the register keyword, you can suggest variables as candidates for 
allocation into registers. 

Eight (nine for the TMS320C4x) registers are available for register variables 
in each function: 

□ Registers R4 and R5 (and R8 for the ’C4x) are reserved for integer register 
variables in a function. 

□ Two registers, R6 and R7, are reserved for floating-point register variables 
in a function. 

□ Four registers, AR4-AR7, are reserved for pointer or integer register 
variables. 

Any object with a scalar type (integer, floating-point, or pointer) can be de¬ 
clared as a register variable. The register designator is ignored for objects of 
other types. 

The register storage class is meaningful for parameters as well as local vari¬ 
ables. If the stack-based calling convention is used, a parameter declared as 
a register is passed on the stack normally but then moved into a register upon 
function entry. This improves access to the parameter within the function. If a 
parameter is not declared as a register, it will be allocated local space in the 
function and stored there as the function begins execution. 

For more information about register variables, refer to Section 4.3 on 
page 4-11. 


3-10 


Pragma Directives 


3.5 Pragma Directives 

Pragma directives tell the compiler’s preprocessor how to treat functions. The 
TMS320C3x/C4x C compiler supports the following pragmas: 

□ CODE_SECTION 

□ DATASECTION 

□ FUNC_CANNOT_INLINE 

□ FUNC_EXT_CALLED 

□ FUNC_IS_PURE 

□ FUNC_IS_SYSTEM 

□ FUNC_NEVER_RETURNS 

□ FUNC_NO_GLOBAL_ASG 

□ FUNC_NO_IND_ASG 

□ INTERRUPT 

The arguments func and symbol must have file scope; that is, you cannot 
define or declare them inside the body of a function. You must specify the 
pragma outside the body of a function, and it must occur before any declara¬ 
tion, definition, or reference to the func or symbol argument. If you do notfollow 
these rules, the compiler issues a warning. 


TMS320C3x/C4x C Language 


3-11 


Pragma Directives 


3.5.1 The CODE SECTION Pragma 

The CODE_SECTION pragma allocates space for the symbol in a section 
named section name. The syntax of the pragma is: 


#pragma CODE_SECTION (symbol, “section name")-, 


The section will be declared by the compiler with the .sect assembler directive. 
If you use a section name longer than eight characters, you must use COFF2. 

The CODE_SECTION pragma is useful if you have code objects that you want 
to link into an area separate from the .bss section. 

Example 3-2 demonstrates the use of the CODE_SECTION pragma. 

Example 3-2. Using the CODE SECTION Pragma 

(a) C source file 


#pragma CODE_SECTION(fn, 

int fn(int x) 

{ 

return c; 

} 

"my_sect") 

(b) Assembly source file 

.sect "my_sect" 


.global _fn 
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3.5.2 The DATASECTION Pragma 

The DATA_SECTION pragma allocates space for the symbol in a section 
named section name. The syntax of the pragma is: 


#pragma DATA_SECTION ( symbol , “section name")-, 


The DATA_SECTION pragma is useful if you have data objects that you want 
to link into an area separate from the .bss section. 

If you use a section name longer than eight characters, you must use COFF2. 
Example 3-3 demonstrates the use of the DATA_SECTION pragma. 

Example 3-3. Using the DATA SECTION Pragma 

(a) C source file 

#pragma DATA_SECTION(bufferB, "my_sect") 
char bufferA[512]; 
char bufferB[512]; 


(b) Assembly source file 


.global 

_bufferA 

.bss 

_bufferA,512 

.global 

_bufferB 

_bufferB: 

.usect "my_sect",512, 1 


3.5.3 The FUNC_CANNOTJNLINE Pragma 

The FUNC_CANNOT_INLINE pragma instructs the compiler that the named 
function cannot be expanded inline. Any function named with this pragma 
overrides any inlining you designate in any other way, such as using the inline 
keyword. 

The pragma must appear before any declaration or reference to the function 
that you want to keep. The syntax of the pragma is: 


#pragma FUNC_CANNOT_INLINE (tunc); 


The argument tunc is the name of the C function that cannot be inlined. For 
more information, see Section 2.5, Function Inlining, on page 2-43. 
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3.5.4 The FUNC_EXT_CALLED Pragma 

When you use the -pm option, the compiler uses program-level optimization. 
When you use this type of optimization, the compiler removes any function that 
is not called, directly or indirectly, by main. You might have C functions that are 
called by hand-coded assembly instead of main. 

The FUNC_EXT_CALLED pragma specifies to the optimizer to keep these C 
functions or any other functions that these C functions call. These functions 
act as entry points into C. 

The pragma must appear before any declaration or reference to the function 
that you want to keep. The syntax of the pragma is: 


#pragma FUNC_EXT_CALLED ( func ); 


The argument fund s the name of the C function that you do not want removed. 

3.5.5 The FUNC_IS_PURE Pragma 

The FUNC_IS_PURE pragma specifies to the optimizer that the named func¬ 
tion has no side effects. This allows the optimizer to do the following: 

□ Delete the call to the function if the function’s value is not needed 

□ Delete duplicate functions 

The pragma must appear before any declaration or reference to the function. 
The syntax of the pragma is: 


#pragma FUNC_IS_PURE (fund); 


The argument func is the name of a C function. 
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3.5.6 The FUNCJS_SYSTEM Pragma 

The FUNC_IS_SYSTEM pragma specifies to the optimizer that the named 
function has the behavior defined by the ANSI standard for a function with that 
name. 

The pragma must appear before any declaration or reference to the function 
that you want to keep. The syntax of the pragma is: 


#pragma FUNC_IS_SYSTEM (fund); 


The argument func is the name of the C function to treat as an ANSI standard 
function. 

3.5.7 The FUNC_NEVER_RETURNS Pragma 

The FUNC_NEVER_RETURNS pragma specifies to the optimizer that the 
function never returns to its caller. 

The pragma must appear before any declaration or reference to the function 
that you want to keep. The syntax of the pragma is: 


#pragma FUNC_NEVER_RETURNS (func); 


The argument func is the name of the C function that does not return. 

3.5.8 The FUNC_NO_GLOBAL_ASG Pragma 

The FUNC_NO_GLOBAL_ASG pragma specifies to the optimizer that the 
function makes no assignments to named global variables and contains no 
asm statements. 

The pragma must appear before any declaration or reference to the function 
that you want to keep. The syntax of the pragma is: 


#pragma FUNC_NO_GLOBAL_ASG (func); 


The argument func is the name of the C function that makes no assignments. 
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3.5.9 The FUNC_NOJND_ASG Pragma 

The FUNC_NO_IND_ASG pragma specifies to the optimizer that the function 
makes no assignments through pointers and contains no asm statements. 

The pragma must appear before any declaration or reference to the function 
that you want to keep. The syntax of the pragma is: 


#pragma FUNC_NO_IND_ASG (fund)-, 


The argument func is the name of the C function that makes no assignments. 

3.5.10 The INTERRUPT Pragma 

The INTERRUPT pragma enables you to handle interrupts directly with C 
code. The argument func is the name of a function. The pragma syntax is: 


#pragma INTERRUPT (func)-, 


Except for cJntOO, which is the name reserved for the system reset interrupt 
for C programs, the name of the interrupt (the func argument) does not need 
to conform to a naming convention. 
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3.6 The asm Statement 

The TMS320C3x/C4x C compiler allows you to imbed TMS320C3x/C4x 
assembly language instructions or directives directly into the assembly lan¬ 
guage output of the compiler. This capability is provided through an extension 
to the C language: the asm statement. The asm statement is syntactically like 
a call to a function named asm, with one string-constant argument: 

asm {"assembler text"); 

The compiler copies the argument string directly into your output file. The 
assembler text must be enclosed in double quotes. All the usual character 
string escape codes retain their definitions. For example, you can insert a 
.string directive that contains quotes: 

asm("STR: .string \"abc\""); 

The inserted code must be a legal assembly language statement. Like all 
assembly language statements, the line musfbegin with a label, a blank, a tab, 
or a comment (asterisk or semicolon). The compiler performs no checking on 
the string; if there is an error, it will be detected by the assembler. For more 
information, refer to the TMS320C3x/C4x Assembly Language Tools User’s 
Guide. 

These asm statements do not follow the syntactic restrictions of normal C 
statements: they can appear as either a statement or a declaration, even out¬ 
side blocks. This is particularly useful for inserting directives at the very begin¬ 
ning of a compiled module. 

I-1 

Note: Avoid Disrupting the C Environment With asm Statements 

Be extremely careful not to disrupt the C environment with asm statements. 
The compiler does not check the inserted instructions. Inserting jumps and 
labels into C code can cause unpredictable results in variables manipulated 
in or around the inserted code. Directives that change sections or otherwise 
affect the assembly environment can also be troublesome. Be especially 
careful when you use the optimizer with asm statements. Although the opti¬ 
mizer cannot remove asm statements (except where such statements are 
totally unreachable), it can significantly rearrange the code order near asm 
statements, possibly causing undesired results. The asm command is pro¬ 
vided so that you can access features of the hardware, which, by definition, 
C is unable to access. 

i_i 
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3.7 Initializing Static and Global Variables 

The ANSI C standard specifies that static and global variables without explicit 
initializations must be specifically initialized to zero before the program begins 
running. This task is typically done when the program is loaded. Because the 
loading process depends heavily on the specific environment of the target 
application system, the TMS320C3x/C4x C compiler itself does not preinitial¬ 
ize variables; therefore, it is up to your application to fulfill this requirement. 

If your loader does not preinitialize variables, you can use the linker to 
preinitialize the variables to 0 in the object file. In the linker command file, use 
a fill value of 0 in the .bss section: 

SECTIONS 


.bss: {} = 0x00; 


} 

Because the linker writes a complete load image of the zeroed .bss section into 
the output COFF file, this method may have the unwanted effect of significantly 
increasing the size of the output file. 

Initializing Static and Global Variables With the const Type Qualifier 

Static and global variables with the type qualifier const are initialized 
differently than other types of static and global variables. 

const static and global variables without explicit initializations may or may not 
not be preinitialized to zero, for the same reasons discussed in Section 3.7. 
For example: 

const int zero; /* may not be initialized to zero */ 

All constants that initialize global variables (with or without the const qualifier) 
will be placed in the .cinit section. All constants contained in expressions or 
that initialize local variables (with or without the const qualifier) will either be 
placed in the CONST table or will be loaded with immediate addressing. 

Values initialized with the const qualifier are not placed in the .const section 
because the values must be accessed with direct addressing. With the small 
memory model, it would be necessary to require that the .bss and the .const 
sections be on the same data page if the values were placed in the .const 
section. 
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□ Integer constant expressions wider than 16 bits 

□ Floating-point constant expressions with exponents larger than 4 bits or 
mantissas larger than 11 bits 

□ Integer local variable initializers wider than 16 bits 

□ Floating-point local variable initializers with exponents larger than 4 bits 
or mantissas larger than 11 bits 

□ Addresses of global variables 

□ Addresses of string constants 

The .const section contains the following: 

□ Tables for switch statements 

□ String constants that do not initialize global variables 

□ The CONST table when using big model 
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3.8 Far Call Support 

A function can be declared with the keyword far to signify to the compiler that 
calls to that function should be made using a 32-bit far call (an indirect call 
through a register) instead of a label. The resulting assembly code will load the 
address of the function into a register and then call unconditionally to that reg¬ 
ister. The far call allows address offsets of greater than 16 bits to be used when 
calling that function, at the cost of one additional instruction (the address load). 

The compiler is required to make calls to certain runtime-support assembly 
functions to accomplish various initialization and arithmetic tasks. (These 
functions are listed in Table 4-3 on page 4-19.) The shell’s -ml option (page 
2-21) can be used to cause the compiler to generate far calls to these func¬ 
tions. Using far calls in this way may be appropriate if, for example, functions 
that call the runtime-support functions are separated from them by offsets of 
greater than 16 bits. 

To make far calls to other runtime-support functions, you must extract the 
source files from the rts.src file, add the far keyword to the desired functions, 
and then recompile the library. The library-build utility described in Section 6.1 
allows you to extract source files and recompile the library. 

It is important to add the far keyword to the function prototypes in the appropri¬ 
ate include files to ensure far call generation in the source files. 
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3.9 Delay Slot Filling for Branches 

The compiler includes support for filling the three delay slots generated by the 
TMS320C3x/C4x for branches. 

The compiler handles unconditional branches by first trying to fill the delay 
slots with instructions located before the branch. It will then try to move up in¬ 
structions from the destination block. Almost any type of instruction can be 
moved, except for those that modify the PC. 

Conditional branches are handled a little differently. The compiler will try to fill 
delay slots with: 

□ conditional load instructions that include known, “safe" source operands 
(such as local auto variables, parameters, and constants). If you know that 
all memory will return an appropriate value when accessed, you can use 
the -ms shell option to inform the compiler that these constraints are not 
necessary when filling delay slots. 

□ instructions located immediately following the delay slots of the 
conditional block (i.e., instructions that will be executed if the condition is 
false) 

□ instructions located at the destination block (i.e., instructions that will be 
executed if the condition is true) 

If the shell option -mp is used, the compiler will try to copy instructions rather 
than moving them, which can lead to significant increases in speed. 

If the compiler cannot fill any, or at least a majority, of the delay slots, it will con¬ 
dense the delayed branch into a non-delayed branch instruction (unless the 
-mp option has been specified). Any instructions found in the delay slots will 
be placed before the branch instruction. The compiler makes this change in 
an attempt to conserve code size by deleting the NOPs that would normally 
be placed in the empty delay slots. If the -mp option has been specified, the 
compiler will not condense delayed branches in this manner, but will leave 
branches even with only one slot filled in an attempt to take advantage of cycle 
savings. 
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3.10 Compatibility With K&R C (-pk Option) 

The ANSI C language is a superset of the de facto C standard defined in the 
first edition of The C Programming Language (K&R). Most programs written 
for earlier non-ANSI C versions of the TMS320C3x/C4x C compiler and other 
non-ANSI compilers should correctly compile and run without modification. 

However, there are subtle changes in the language that may affect existing 
code. Appendix C in K&R (second edition) summarizes the differences be¬ 
tween ANSI C and the previous C standard, called K&R C. 

To simplify the process of compiling existing C programs with the 
TMS320C3x/C4x ANSI C compiler, the compiler has a K&R option (-pk) that 
modifies some of the semantic rules of the language for compatibility with older 
code. In general, the-pk option relaxes requirements that are stricter for ANSI 
C than for previous C standards. The -pk option does not disable any new 
features of the language such as function prototypes, enumerations, 
initializations, or preprocessor constructs. Instead, -pk simply liberalizes the 
ANSI rules without revoking any of the features. 

The specific effects of -pk are include: 

□ The integral promotion rules have changed regarding promoting an un¬ 
signed type to a wider, signed type. Under K&R, the result type was an 
unsigned version of the wider type; under ANSI, the result type is a signed 
version of the wider type. This affects options that perform differently when 
applied to signed or unsigned operands. Namely, comparisons, division 
(and mod), and right shift. In this example, assume that short is narrower 
than int: 

unsigned short u 
int i; 

if (u<i) .../* SIGNED comparison, unless -pk used */ 

□ ANSI prohibits two pointers to different types from being combined in an 
operation. In most K&R compilers, this situation is only a warning. Such 
cases are still diagnosed when -pk is used, but with less severity: 

int *p; 

char *q = p; /* error without -pk, warning with -pk */ 

Even without -pk, a violation of this rule is a code-E (recoverable) error. An 
alternative to using -pk to work around this situation is to use -pe, which 
converts code-E errors to warnings. 

□ External declarations with no type or storage class (identifier only) are ille¬ 
gal in ANSI but legal in K&R: 

a; /* illegal unless -pk used */ 


3-22 


Compatibility With K&R C (-pk Option) 


□ ANSI interprets file scope definitions that have no initializers as tentative 
definitions', in a single module, multiple definitions of this form are fused 
together into a single definition. Under K&R, each definition is treated as 
a separate definition, resulting in multiple definitions of the same object 
(and usually an error). For example: 

int a; 

int a; /* illegal if -pk used, OK if not */ 

Under ANSI, the result of these two declarations is a single definition for 
the object a. For most K&R compilers, this sequence is illegal because a is 
defined twice. 

□ ANSI prohibits, but K&R allows, objects with external linkage to be 
redeclared as static: 

extern int a; 

static int a; /* illegal unless -pk used */ 

□ Unrecognized escape sequences in string and character constants are 
explicitly illegal under ANSI but ignored under K&R: 

char c = '\q'; /* same as 'q' if -pk used, error 

if not */ 

□ ANSI specifies that bit fields must be of type integer or unsigned. With -pk, 
bit fields can be legally declared with any integer type. For example, 

struct s 
{ 

short f : 2; /* illegal unless -pk used */ 

} ; 

□ K&R syntax allows assignments to structures returned from a function: 

f () .x = 123 /* illegal unless -pk used */ 

□ K&R syntax allows a trailing comma in enumerator lists: 

enum { a, b, c, }; /* illegal unless -pk used */ 

□ K&R syntax allows trailing tokens on preprocessor directives: 

#endif NAME /* illegal unless -pk used */ 
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3.11 Compiler Limits 

Due to the variety of host systems supported by the TMS320C3x/C4x C 
compiler and the limitations of some of these systems, the compiler may not 
be able to successfully compile source files that are excessively large or com¬ 
plex. Most of these conditions occur during the first compilation pass (parsing). 
When such a condition occurs, the parser issues a code-1 diagnostic message 
indicating the condition that caused the failure; usually the message also spec¬ 
ifies the maximum value for whatever limit has been exceeded. The code 
generator also has compilation limits but fewer than the parser. 

In general, exceeding any compiler limit prevents continued compilation, so 
the compiler aborts immediately after printing the error message. The only way 
to avoid exceeding a compiler limit is to simplify the program or parse and pre- 
process in separate steps. 

Many compiler tables have no absolute limits but rather are limited only by the 
amount of memory available on the host system. Table 3-3 specifies the limits 
that are absolute. When two values are listed, the first is for PCs (DOS or 
OS/2), and the second is for other hosts. All the absolute limits equal or exceed 
those required by the ANSI C standard. 

On smaller host systems such as PCs, the optimizer may run out of memory. 
If this occurs, the optimizer terminates and the shell continues compiling the 
file with the code generator. This results in a file compiled with no optimization. 
The optimizer compiles one function at a time, so the most likely cause of this 
is a large or extremely complex function in your source module. To correct the 
problem, your options are: 

□ don’t optimize the module in question 

□ identify the function that caused the problem and break it down into 
smaller functions 

□ extract the function from the module and place it in a separate module that 
can be compiled without optimization so that the remaining functions can 
be optimized. 

□ Use the protected-mode compiler 
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Table 3-3. Absolute Compiler Limits 


Description 

Limits 


Filename length 

256 characters 


Source line length 

16K characters 

(see note 1) 

Length of strings built from # or ## 

512 characters 

(see note 2) 

Macro definitions 

Allocated from available system 
memory 

Macros predefined with -d 

32 


Macro parameters 

32 


Macro nesting 

32 levels 

(see note 3) 

#include search paths 

32 paths 

(see note 4) 

#include file nesting 

32 levels 


Conditional inclusion (#if) nesting 

32 levels 


Nesting of struct, union, or prototype dec¬ 
larations 

20 levels 


Function parameters 

32 parms 


Array, function, or pointer derivations on 
a type 

12 derivations 


Aggregate initialization nesting 

32 levels 


Static initializers 

= 1500 per initialization 


Local initializers 

= 150 per block 


Nesting of declarations in structs, unions, 
or prototypes 

32 levels 


Global symbols 

2000 

PCs 


10000 

All others 

Block scope symbols visible at any point 

500 

PCs 


1000 

All others 

Number of unique string constants 

400 

PCs 


1000 

All others 

Number of unique floating-point 

400 

PCs 

constants 

2000 

All others 


Notes: 1 ) After splicing of \ lines. This limit also applies to any single macro definition or invoca¬ 
tion. 

2) Before concatenation. All other character strings are unrestricted. 

3) Includes argument substitutions. 

4) Includes -i and C_DIR directories. 
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Runtime Environment 


This section describes the TMS320C3x/C4x C runtime environment. To 
ensure successful execution of C programs, it is critical that all runtime code 
maintain this environment. If you write assembly language functions that inter¬ 
face to C code, follow the guidelines in this chapter. 

Topics in this chapter include: 


Topic 


Page 


4.1 

Memory Model. 

F2| 

4.2 

Object Representation. 

4-7 

4.3 

Register Conventions . 

4-11 

4.4 

Function Structure and Calling Conventions . 

4-15 

4.5 

Interfacing C with Assembly Language . 

4-22 

4.6 

Interrupt Handling. 

4-30 

4.7 

Runtime-Support Arithmetic Routines . 

4-32 

4.8 

System initialization. 

4-36 
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4.1 Memory Model 

The C compiler treats memory as a single linear block that is partitioned into 
subblocks of code and data. Each block of code or data that a C program gen¬ 
erates will be placed in its own contiguous space in memory. The compiler 
assumes that a full 32-bit address space is available in target memory. 

I-1 

Note: The Linker Defines the Memory Map 

The linker, not the compiler, , defines the memory map and allocates code 
and data into target memory. The compiler assumes nothing about the types 
of memory available, about any locations not available for code or data 
(holes), or about any locations reserved for I/O or control purposes. The 
compiler produces relocatable code that allows the linker to allocate code 
and data into the appropriate memory spaces. For example, you can use the 
linker to allocate global variables into fast internal RAM or to allocate 
executable code into internal ROM. Each block of code or data could be allo¬ 
cated individually into memory, but this is not a general practice. (An 
exception to this is memory-mapped I/O, although physical memory loca¬ 
tions can be accessed with C pointer types.) 

I_I 


4.1.1 Sections 


The compiler produces six relocatable blocks of code and data; these blocks, 
called sections, can be allocated into memory in a variety of ways, to conform 
to a variety of system configurations. For more information about sections, 
please read the Introduction to Common Object File Format in the 
TMS320C3x/C4x Assembly Language Tools User’s Guide. 

There are two basic types of sections: 

□ Initialized sections contain data or executable code. The C compiler 

creates three initialized sections: .text, .cinit, and .const. 

■ The .text section is an initialized section that contains all the 
executable code as well as floating-point constants. 

■ The .cinit section is an initialized section that contains tables with the 
values for initializing variables and constants. 

■ The .const section is an initialized section that contains floating-point 
constants and switch tables. 
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□ Uninitialized sections reserve space in memory (usually RAM). A pro¬ 
gram can use this space at runtime for creating and storing variables. The 
compiler creates three uninitialized sections: .bss, .stack, and .sysmem. 
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■ The .bss section reserves space for global and static variables; in the 
small model, the .bss section also reserves space for the constant 
table. At program startup, the C boot routine copies data out of the 
.cinit section (which may be in ROM) and stores it in the .bss section. 

■ The .stack section allocates memory for the system stack. This 
memory is used to pass arguments to functions and to allocate local 
variables. 

■ The .sysmem section is a memory pool, or heap, used by the 
dynamic memory functions, malloc, calloc, and realloc. If a program 
does not link these functions, the linker does not create the .sysmem 
section. 

For the TMS320C32 only, the .sysm8 section and .sysml 6 section 
are used by special 8-bit and 16-bit versions of the dynamic memory 
management functions. See Section 4.1.3 for more information. 

The linker takes the individual sections from different models and combines 
sections with the same name to create output sections. Note that the 
assembler creates three default sections (.text, .bss, and .data); the C 
compiler, however, does not use the .data section. 

The complete program is made up of the compiler output sections, plus the 
assembler’s .data section. The linker takes the individual sections from differ¬ 
ent modules and combines sections having the same name to create the 
output sections. You can place these output sections anywhere in the address 
space, as needed, to meet system requirements. The .text, .cinit, .const, and 
.data sections can be linked into either ROM or RAM. The .bss, .stack, and 
.sysmem sections should be linked into some type of RAM. Note, however, 
that the .bss and .const sections must be allocated in the same 64K data page 
for a small model, see page 4-5. 

For more information about allocating sections into memory, see the 
TMS320C3x/C4x Assembly Language Tools User’s Guide. 

4.1.2 C System Stack 

The C compiler uses a software stack to: 

□ Save function return addresses 

□ Allocate local variables 

□ Pass arguments to functions 

□ Save temporary results 

□ Save registers 

□ Save the processor status 
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The runtime stack grows up from low addresses to higher addresses. The 
compiler uses two auxiliary registers to manage this stack: 

SP is the stack pointer (SP); it points to the current top of the stack. 

AR3 is the frame pointer (FP); it points to the beginning of the current 
frame. Each function invocation creates a new frame at the top of the 
stack, from which local and temporary variables are allocated. 

The C environment manipulates these registers automatically. If you write any 
assembly language routines that use the runtime stack, be sure to use these 
registers correctly. (For more information about using these registers, see 
Section 4.3, page 4-11; for more information about the stack, see Section 4.4, 
page 4-15.) 

The stack size is set by the linker. The linker also creates a global symbol, 

_STACK_SIZE, and assigns it a value equal to the size of the stack in 

words. The default stack size is 1K (400h) words. This size allows the stack to 
fit into one of the on-chip RAM blocks. You can change the size of the stack at 
link time by using the -stack option on the linker command line and specifying 
the size of the stack as a constant immediately after the option. For more 
information about the -stack option, refer to the TMS320C3x/C4x Assembly 
Language Tools User’s Guide. 

At system initialization, the SP is set to a designated address for the bottom- 
of-stack. This address is the first location in the .stack section. Since the 
position of the stack depends on where the .stack section is allocated, the 
actual position of the stack is determined at link time. If you allocate the stack 
as the last section in memory (highest address), the stack has unlimited 
space for growth (within the limits of system memory). 

I-1 

Note: Stack Overflow 

The compiler provides no means to check for stack overflow during compila¬ 
tion or at runtime. A stack overflow will disrupt the runtime environment, 
causing your program to fail. Be sure to allow enough space for the stack to 
grow. 

I_I 

4.1.3 Dynamic Memory Allocation 

The runtime-support library supplied with the compiler contains several 
functions (such as malloc, calloc, and realloc) that allow you to dynamically 
allocate memory for variables at runtime. Dynamic allocation is not a standard 
part of the C language; it is provided by standard runtime-support functions. 

Memory is allocated from a global pool, or heap, that is defined in the 
.sysmem section. You can set the size of the .sysmem section by using the 
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-heap option when you link your program. Specify the size of the memory 
pool as a constant after the -heap option on the linker command line. The 

linker also creates a global symbol,_SYSMEM_SIZE, and assigns it a value 

equal to the size of the heap in words. The default size is 1K words. For more 
information on the heap option, refer to the TMS320C3x/C4x Assembly 
Language Tools User’s Guide. 

Dynamically allocated objects are not addressed directly (they are always 
accessed with pointers), and the memory pool is in a separate section; 
therefore, the dynamic memory pool can have an unlimited size, even in the 
small memory model. This allows you to use the more efficient small memory 
model, even if you declare large data objects. To conserve space in the .bss, 
you can allocate large arrays from the heap instead of declaring them as 
global or static. For example, instead of a declaration such as: 

struct big table[10000]; 

use a pointer and call the malloc function; 

struct big *table 

table = (struct big *)malloc(10000 * sizeof (struct big)); 

For the TMS320C32, the runtime support library contains the following 8-bit 
and 16-bit versions of the dynamic memory management functions: 

calloc8, free8, malloc8, bmalloc8, minit8, realloc8 
callocl6, freel6, mallocl6, bmallocl6, minitl6, reallocl6 

These functions allocate space from the .sysm8 and .sysm16 uninitialized 
sections rather than the .sysmem section. The sizes of the .sysm8 and 
,sysm16 sections are set by specifying the -heap8 and -heap16 linker 
options, respectively. If the 8-bit or 16-bit memory management functions are 
used but the -heap8 and -heapl 6 options are not specified, the linker will allo¬ 
cate the default size of IK 8-bit or 16-bit words. The 8-bit or 16-bit memory 
functions cause the linker to set the constant heap size values for the 
_SYSMEM8_SIZE and_SYSMEM16_SIZE symbols. The stdlib.h header file 
should be included in any file that uses these functions. 

4.1.4 Big and Small Memory Models 

The compiler supports two memory models that affect how .bss is allocated 
into memory. Neither model restricts the size of the .text or .cinit sections. Both 
models restrict the size of a single function to 32K words of code or less; this 
allows the compiler to use relative conditional jumps over the entire range of 
the function. 

□ The small memory model, which is the default, requires that the entire 
.bss section fit within a single 64K-word memory data page (65536 words). 
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This means that the total space for all static and global data in the program 
must be less than 64K and that the .bss cannot cross any 64K address 
boundaries. The compiler sets the data-page pointer register (DP) during 
runtime initialization to point to the beginning of the .bss. Then the com¬ 
piler can access all objects in the .bss (global and static variables and 
constant tables) with direct addressing (@) without modifying the DP. 

□ The big memory model does not restrict the size of the .bss; unlimited 
space is available for global and static data. However, when the compiler 
accesses any global or static object that is stored in the .bss, it must first 
ensure that the DP correctly identifies the memory page where the object 
is stored. To accomplish this, the compiler must set the DP by using an 
LDP or LDPK (load data-page pointer) instruction each time a static or 
global data item is accessed. This task produces one extra instruction 
word and several extra machine cycles (one cycle for the LDP instruction 
plus one or more pipeline delay cycles if the object is accessed by the next 
instruction). 

For example, the following compiler-generated assembly language uses 
the LDP instruction to set the DP to the correct page before accessing the 
global variable x. This is a TMS320C3x example (the sequence is one 
cycle shorter for the ’C4x): 

*** _x is a global variable *** 

LDP _x ; 1 extra word, 1 cycle 

LDI @_x,R0 ; 3 cycles (2 pipeline delays) 

To use the big memory model, invoke the compiler with the -mb option. 
For more information, refer to Section 2.3, Using Runtime Models, on 
page 2-35. 

4.1.5 RAM and ROM Models 

The C compiler produces code that is suitable for use as firmware in a 
ROM-based system. In such a system, the initialization tables in the .cinit 
section (used for initialization of globalsand statics) are stored in ROM. At sys¬ 
tem initialization time, the C boot routine copies data from these tables from 
ROM to the initialized variables in .bss (RAM). 

In situations where a program is loaded directly from an object file into memory 
and then run, you can avoid having the .cinit section occupy space in memory. 
A user-defined loader can read the initialization tables directly from the object 
file (instead of from ROM) and perform the initialization directly at load time 
(instead of at runtime). You can specify this to the linker by using the -cr linker 
option. For more information, refer to Section 4.8, System Initialization, on 
page 4-36. 
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4.2 Object Representation 

This section explains how various data objects are sized, aligned, and 
accessed. 

4.2.1 Data Type Storage 

□ All basic types are 32 bits wide and stored in individual words of memory. 
No packing is performed except on bitfields, which are packed into words. 
Bit fields are allocated from LSB (least significant bit) to MSB in the order 
in which they are declared. 

□ No object has any type of alignment requirement; any object can be stored 
on any 32-bit word boundary. Objects that are members of structures or 
arrays are stored just as they are individually. Members are not packed 
into structures or arrays (unless the members are bit fields). 

□ The integer types char, short, int, and long are all equivalent, as are their 
unsigned counterparts. Objects of type enum are also represented as 
32-bit words. 

□ The float and double types are equivalent; both types specify objects rep¬ 
resented in the TMS320C3x/C4x 32-bit floating-point format. 

□ The long double type is represented in the TMS320C3x/C4x 40-bit format. 

For more information on data types, refer to Section 3.2, Data Types, on 
page 3-4. 

4.2.2 Long Immediate Values 

The TMS320C3x/C4x instruction set has no immediate operands that are 
longer than 16 bits. The compiler occasionally needs to use constants that are 
too long to be immediate operands. This occurs with signed integer constants 
that have more than 15 significant nonsign bits, with unsigned integers that 
have more than 16 significant bits, or with floating-point constants that have 
more than 11 significant nonsign bits in the mantissa. 

4.2.3 Addressing Global Variables 

The compiler generates the addresses of global and static symbols for index¬ 
ing arrays or manipulating pointers. Because these addresses may be up to 
32 bits wide and immediate operands are limited to 16 bits, these addresses 
are treated like long constants. Subsection 4.2.5 on page 4-9 describes the 
structure of the constant table. 
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4.2.4 Character String Constants 

In C, a character string constant can be used in either of two ways: 

□ It can initialize an array of characters; for example: 

char s[ ] = "abc"; 

When a string is used as an initializer, it is simply treated as an initialized 
array; each character is a separate initializer. For more information about 
initialization, refer to Section 4.8, System Initialization, on page 4-36. 

□ It can be used in an expression; for example: 

strcpy (s, "abc"); 

When a string is used in an expression, the string itself is defined in the 
.const section with the .byte assembler directive, along with a unique label 
that points to the string (the terminating 0 byte is also included). In the 
following example, the label SL5 points to the string from the example 
above: 

.const 

SL5 .byte "abc", 0 

String labels have the form SLn, n being a number assigned by the 
compiler to make the label unique. These numbers begin at 0 with an 
increase of 1 for each string defined. All strings used in a source module 
are defined at the end of the compiled assembly language module. 

The label SLn represents the address of the string constant. The compiler 
uses this label to reference the string in the expression. Like all addresses 
of static objects, this address must be stored in the constant table in order 
to be accessed. Thus, in addition to storing the string itself in the .const 
section, the compiler uses the following directive statement to store the 
string’s address in the constant table: 

.word SLn 

If the same string is used more than once within a source module, the 
string will not be duplicated in memory. All uses of an identical string 
constant share a single definition of the string. 

Because strings are stored in the .const section (possibly in ROM) and 
shared, it is bad practice for a program to modify a string constant. The 
following code is an example of incorrect string use: 

char *a = "abc" 

a[1] = 'x'; /* Incorrect! */ 


4-8 


Object Representation 


4.2.5 The Constant Table 


The constant table contains definitions of all the objects that the compiler must 
access, but are too wide to be used as immediate operands. Such objects 
include: 

□ integer constants that are wider than 16 bits 

□ floating-point constants that have exponents larger than 4 bits or 
mantissas larger than 11 bits 

□ integer local variable initializers wider than 16 bits 

□ floating-point local variable initializers with exponents larger than 4 bits or 
mantissas larger than 11 bits 

□ addresses of global variables 

□ addresses of string constants 

The constant table is simply a block of memory that contains all such objects. 
The compiler builds the constant table at the end of the source module by using 
the .word and .float assembler directives. Each entry in the table occupies one 
word. The label CONST is the address of the beginning of the table. For exam¬ 
ple: 


CONST: .word 011223344h 
.float 3.14159265 
.word _globvar 
.word SL23 


32 bit constant 
floating-point 
address of global 
address of string 


Objects in the table are accessed with direct addressing; for example: 


LDI 


@const+offset, RO 


In this example, offset is the index into the constant table of the required object. 
As with string constants, identical constants used within a source module 
share a single entry in the table. 

In the big memory model, the constant table is built in the .const section (and 
is not copied into RAM). The compiler must insure that the DP register is 
correctly loaded before accessing the object in the table, just as with accessing 
global variables. This requires an LDP instruction before each access of the 
constant table. 

The small model, however, avoids the overhead of loading the DP by requiring 
that all directly addressable objects, including all global variables as well as the 
constant table, are stored on the same memory page. Of course, global vari¬ 
ables must be stored in RAM. For the code to be ROM-able, the constant table 
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must be in ROM. In order to get them on the same page, the boot routine must 
copy the constant table from permanent storage in ROM to the global page in 
RAM. The compiler accomplishes this by placing the data for the constant 
table in the .cinit section and allocating space for the table itself .bss. Thus the 
table is automatically built into RAM through the autoinitialization process. 

Note that the small memory model restricts the total size of the global data 
page to 64K words. 

As with all autoinitialization, you can avoid the extra use of memory required 
by the .cinit section by using the -cr linker option and a “smart” loader to per¬ 
form the initialization directly from the object file. For more information about 
autoinitialization, refer to Section 4.8 on page 4-36. 
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4.3 Register Conventions 

Strict conventions associate specific registers with specific operations in the 
C environment. If you plan to interface an assembly language routine to a C 
program, it is important that you understand these register conventions. 

The register conventions dictate both how the code generator uses registers 
and how values are preserved across function calls. There are two types of 
register variable registers, save on call and save on entry. The distinction 
between these two types of register variable registers is the method by which 
they are preserved across calls. It is the called function’s responsibility to pre¬ 
serve save on entry register variables, and the calling function’s responsibility 
to preserve save on call register variables. 

The following table summarizes how the code generator uses the 
TMS320C3x/C4x registers and shows which registers are defined to be pre¬ 
served across function calls. 

Table 4-1. Register Use and Preservation Conventions 


Register 

Usage 

Preserved by Call 

RO 

Integer and float expressions 

Scalar return values 

No 

R1 

Integer and float expressions 

No 

R2-R3 

Integer and float expressions 

No 

R4-R5 

Integer register variables 

Integer part preserved 

R6-R7 

Float register variables 

Floating part preserved 

AR0-AR1 

Pointer expressions 

No 

AR2 

Pointer expressions 

No 

AR3 

Frame Pointer (FP) 

Yes 

AR4-AR7 

Pointer register variables 

Yes 

IRO 

Extended frame offsets 

No 

IR1 

Extended frame offsets 

No 

BK 

Integer expressions 

No 

RC, RS, RE 

Block (structure) copy 

No 

ST 

Status register 

No 

SP 

Stack pointer 

Yes 

DP 

Accessing globals (big model only) 

Yes in small model 

No in big model 

TMS320C4X Only 

R8 

Integer register variables 

Integer part preserved 

R9-R11 

Integer and float variables 

No 
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4.3.1 Register Variables 

Register variables are local variables or compiler temporaries defined to 
reside in a register rather than in memory. Storing local variables in registers 
allows significantly faster access, which improves the efficiency of compiled 
code. Table 4-2 shows the registers that are reserved to store register vari¬ 
ables. 

Table 4-2. Registers Reserved for Register Variables 


Register 

Description 

R4, R5 

Integer register variables 

R6, R7 

Floating-point register variables 

R8 

(’C4x only) Integer register variables 

AR4-AR7 

Pointer register variables 


These registers are preserved across calls. When a function uses register 
variables, it must save the contents of each used register on entrance to the 
function, then restore the saved contents on exit. This ensures that a called 
function does not disrupt the register variables of the caller. 

When you are not using the optimizer (-o option), you can allocate register 
variables with the register keyword. The code generator tries to allocate these 
variables to the registers listed in Table 4-2 if the value needs to be preserved 
across calls. If a function declares more register variables than are available 
for that type, the excess variables are treated as automatic variables and are 
stored in memory on the local frame. 

When you are using the optimizer, the compiler ignores the register keyword 
and treats all variables as register variables. The code generator allocates as 
many variables to registers as possible, based on the life of a variable and 
when it is used. 

In general, registers not listed in Table 4-2 are not preserved across function 
calls, so they are used only for variables that do not overlap any calls. 
However, if the -pm shell option is used to create a single assembly file, the 
code generator can more accurately determine the register usage and thereby 
safely use additional registers not listed in Table 4-2. 

4.3.2 Expression Registers 
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The compiler uses registers not being used for register variables to evaluate 
expressions and store temporary results. The code generator keeps track of 
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the current contents of the registers and attempts to allocate registers for 
expressions in a way that preserves the useful contents in the registers 
whenever possible. This allows the compiler to reuse register data, to take 
advantage of the TMS320C3x/C4x’s efficient register addressing modes, and 
to avoid unnecessary accesses of variables and constants. 

The contents of the expression registers are not preserved across function 
calls. Any register that is being used for temporary storage when a call occurs 
is saved to the local frame before the function is called. This prevents the called 
function from ever having to save and restore expression registers. 

If the compiler needs another register for storing an expression evaluation, a 
register that is being used for temporary storage can be saved on the local 
frame and used for the expression analysis. 

4.3.3 Return Values 

In general, when a value of any scalar type (integer, pointer, or floating-point) 
is returned from a function, the value is placed in register RO when the function 
returns. However, in the register-argument calling convention used for 
runtime support assembly files, pointers are returned in ARO. 

4.3.4 Stack and Frame Pointers 

The TMS320C3x/C4x C compiler uses a conventional stack mechanism for 
allocating local (automatic) variables and passing arguments to functions. 
When a function requires local storage, it creates its own working space (local 
frame) from the stack. The local frame is allocated during the function’s entry 
sequence and deallocated during the return sequence. 

Two registers, the stack pointer (SP) and the frame pointer (FP), manage the 
stack and the local frame. The SP is a TMS320C3x/C4x register dedicated to 
managing the stack. The compiler uses SP in the conventional way: the stack 
grows toward higher addresses, and the stack pointer points to the top location 
(highest memory) on the stack. Register AR3 is dedicated as the frame pointer 
(FP). The FP points to the beginning or bottom of the local frame for the current 
function. All objects stored in the local frame are referenced indirectly through 
the FP. 

Both the FP and the SP must be preserved across function calls. The function 
calls automatically preserve the SP because everything pushed for the call is 
popped on return. The FP is preserved as a specific part of a function’s entry 
and exit sequence. For more information about stack and frame pointer use 
during function calls, refer to Section 4.4, Function Structure and Calling 
Connections, page 4-15. 
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4.3.5 Other Registers 

Other registers that have specific functions are discussed below. 

□ The data-page pointer (DP) is used to access global and static variables. 
In the small model, the DP is set at program startup and never changed. 
If the DP is modified by an assembly language function in the small model, 
the function must preserve the value. 

□ Index registers IRO and IR1 are used for array indexing and when an offset 
of more than 8 bits (±255 words) is required for indirect addressing. In 
addition, the compiler can use both for a general-purpose integer register 
variable if it is not needed for other purposes. Neither register is preserved 
across calls. 

□ The BK register is used by the compiler as an integer register variable. Its 
value is not preserved across calls. 

□ The compiler uses block-repeat registers (RC, RE, and RS) to generate 
efficient block copy operations for assigning large (>5 words) structures. 
These registers can be used for integer register variables if not being used 
for block copy operations. The repeat register values are not preserved 
across calls; therefore, no calls can be made inside of a loop structured 
with RPTB or RPTS instructions. 
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4.4 Function Structure and Calling Conventions 

The C compiler imposes a strict set of rules on function calls. Except for special 
runtime-support functions, any function that calls or is called by a C function 
must follow these rules. Failure to adhere to these rules can disrupt the C 
environment and cause a program to fail. 

Figure 4-1 illustrates a typical function call. In this example, parameters are 
passed to the function, and the function uses local variables. On the “Before 
Call” stack, SP points to the last saved register, and FP points to the previous 
FP. The “Push Arguments” stack displays the stack just before executing the 
first assembly instruction of the called function (after the last instruction of the 
calling function). The “Allocate Local Frame” stack displays the stack after all 
frame allocation. On this stack, SP points to the last saved register. This 
example shows allocation of a local frame for the called function. Functions 
that have no arguments passed on the stack and no local variables do not allo¬ 
cate a local frame. 

If you use the register-argument model (see Section 4.4.2), some or all of the 
arguments may be passed in registers rather than on the stack as shown. 
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Figure 4-1. Stack Use During a Function Call 
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CALL 



Push Arguments, 
Call Function 
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Local Frame 



4.4.1 Function Call, Standard Runtime Model 

In general, a function performs the following tasks when it calls another 

function. 

1) The caller pushes the arguments on the stack in reverse order (the right¬ 
most declared argument is pushed first, and the leftmost is pushed last). 
This places the leftmost argument at the top of the stack when the function 
is called. 

2) The caller calls the function. 

3) When the called function is complete, the caller pops the arguments off the 
stack with the following instruction: 

subi n, sp (n is the number of argument words that were pushed) 
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4.4.2 Function Call, Register Argument Runtime Model 

In general, when the register argument model is in use, a function performs 
the following tasks when it calls another function. 

1) Six registers, AR2, R2, R3, RC, RS, and RE, are used to pass arguments 
as follows: 

■ The first two (left-most) floating-point (float, double, or long double) 
arguments are passed in R2 and R3. 

■ The remaining integer or pointer arguments are passed in the remain¬ 
ing registers in the above list, in order. Note that structures and unions 
can be passed by address as an integer argument. 

■ All arguments that are not assigned to registers, either because of 
type incompatibility or because all registers have been exhausted, are 
pushed onto the stack in reverse order (right-to-left). 

A seventh register, ARO, may be used to return structures and unions 
by address. 

In Figure 4-2, several function prototypes are shown with the location 
of each argument indicated to illustrate the conventions. 


Figure 4-2. Register Argument Conventions 


int 

fl 

(int *a. 

int b, 

int c) ; 

/* function call 

*/ 




AR2 

R2 

R3 <— 

-where parameters are placed 


int 

f 2 

(int a, 

float b. 

int *c. 

struct A d, float 

e, Int f); 

/* call */ 



AR2 

R2 

RC 

RS R3 

RE <- 

—parameters 

int 

f 3 

(float a 

, int *b 

, float c 

, int d, float e) 

; /* call 

*/ 



R2 

AR2 

R3 

RC STACK 

<-parameters 

int 

f 4 

( struct 

x a, int 

b, int C 

, int d, int e, int f, int g. 

int h); 



AR2 

R2 R3 

RC RS 

RE STACK 

STACK 


Notice how R2 and R3 are allocated first to any floats in the argument 
list. Then, a second pass allocates remaining arguments to remaining 
registers. 
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If a function is declared with an ellipsis, indicating that it can be called 
with varying numbers of arguments, the convention is modified 
slightly. The last explicitly declared argument is passed on the stack, 
so that its stack address can act as a reference for accessing the 
undeclared arguments. For example: 

int vararg(int a, int b, ...); 

AR2 STACK STACK STACK STACK... 

2) The caller calls the function. 

3) The caller pops the arguments that were passed on the stack, if any. 

Register Argument Model for Runtime-Support Functions 

The runtime-support assembly (.asm) files use a modified version of the 
register argument calling convention. 

Four registers, R1, R2, R3, and R4, are used to pass arguments as follows: 

■ Integer, floating-point, and pointer arguments are passed in the 
registers in the above list, in order. 

■ All arguments that are not assigned to registers, either because of 
type incompatibility or because all registers have been exhausted, are 
pushed onto the stack in reverse order (right-to-left). 

A fifth register, ARO, may be used to return structures and unions by 
address. ARO may also be used to return pointers. 

Table 4-3 lists the functions contained in the runtime-support assembly files 
that conform to the modified calling convention. 
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Table 4-3. Runtime-Support Functions Using Modified Calling Convention 


Function 

Assembly File 

Function 

Assembly File 

_c_int00 

_main 

_exit 

boot.asm 

MPYJ30 

mpyi.asm 

_frexp 

frexp30.asm 

MPY_K30 

mpyk.asm 

Jdexp 

Idexp30.asm 

MPY_LD 

mpyld.asm 

Jongjmp 

_setjmp 

setjmp.asm 

DIV 130 

DIV_140 

divi.asm 

_modf 

modf30.asm 

DIV F30 
DIV_F40 

divf.asm 

_sqrt 

sqrt30.asm 

DIV U30 
DIVJJ40 

divu.asm 

DIV F, DIV 1 

DIV U, MOD 1 
MOD U, MPY 1 
MPY X 

arith410.asm 

DIV_LD 

divld.asm 

o o 

CO ^f- 
LL LL 

>'>' 
z z 

invf.asm 

MOD 130 
MODJ40 

modi.asm 

INV_LD 

invld.asm 

MOD U30 
MODJJ40 

modu.asm 


4.4.3 Responsibilities of a Called Function 

A called function must perform certain tasks. Step 1 below helps to manage 
the local frame. If the function has no local variables, no stack arguments, and 
no need for local temporary storage, Steps 1) and 6) are not taken. 

1) The called function sets up the local frame. The local frame is allocated 
in the following way: 

a) The old frame pointer is saved on the stack. 

b) The new frame pointer is set to the current SP. 

c) The frame is allocated by adding its size to the SP. 
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2) If the called function modifies any of the following registers, it must save 
them on the stack. 


Save as integers Save as floating-point 


R4 

R5 

R6 

R7 

AR4 

AR5 



AR6 

AR7 



FP 

DP (small model 

only) 



R8 (‘C4x only) 




The called function may modify any other registers without saving them. 


3) The called function executes its code. 

4) If the function returns an integer, pointer, or float, it places the return value 
in RO. In the modified register-argument calling convention used for 
runtime support assembly files (page 4-18), pointers are returned in ARO. 

If the function returns a structure, the caller allocates space for the 
structure and then passes the address of the return space to the called 
function in register ARO. To return a structure, the called function then 
copies the structure to the memory block that ARO points to. If the caller 
does not use the return value, ARO is set to 0. This directs the called 
function not to copy the return structure. 

In this way, the caller can be “smart” about telling the called function where 
to return the structure. For example, in the statement s = f(), where s is a 
structure and f is a function that returns a structure, the caller can simply 
place the address of s in ARO and call f. Function f then copies the return 
structure directly into s, performing the assignment automatically. 

You must be careful to properly declare functions that return structures— 
both at the point where they are called (so the caller properly sets up ARO) 
and where they are defined (so the function knows to copy the result). 

5) The called function restores all saved registers. 

6) It deallocates the local frame (if necessary) by subtracting its size from SP 
and restores the old FP by popping it. 

7) It pops the return address and branches to it. In functions with no saved 
registers, this is performed by executing a RETS statement. In other 
functions, the compiler loads the return address into R1 and uses a 
delayed branch to return. The delay slots are used to restore registers and 
deallocate the local frame. 
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4.4.4 Accessing Arguments and Local Variables 

A function accesses its stack arguments and local nonregister variables 
indirectly through the FP, which always points to the bottom of the local frame. 
Because the FP actually points to the old FP, the first local variable is 
addressed as *+FP(1). Other local variables are addressed with increasing 
offsets, up to a maximum of 255. Local objects with offsets larger than 255 are 
accessed by first loading their offset into an index register (IRn) and 
addressing them as *+FP(IRn). 

Stack arguments are addressed in a similar way, but with negative offsets from 
the FP. The return address is stored at the location directly below the FP, so 
the first argument is addressed as *-FP(2). Other arguments are addressed 
with increasing offsets, up to a maximum of 255 words. The IR registers are 
also used to access arguments with offsets larger than 255. 

I-1 

Note: Avoid Locals and Arguments With Large Offsets 

It is desirable to avoid using locals and arguments with offsets larger than 
255 words. However, if you must use locals and/or arguments with large 
offsets, the sequence used to access these variables is: 

LDI offset, IRn 

*+FP(IRn), ... 

This sequence incurs one additional instruction and three additional clock 
cycles each time it is used. If you must use a larger local frame, try to put the 
most frequently used variables within the first 255 words of the frame. 

I_I 

When register arguments are used, it is critically important that the caller and 
callee agree both in type and number of arguments so that the called function 
can find the arguments. Rules for argument passing are described in 
subsection 4.4.2. Arguments passed in registers can remain in those registers 
as long as the register is not needed for expression evaluation. If registers con¬ 
taining arguments must be freed for expression evaluation, they can be copied 
to the local frame or other registers at function entry. 

When you are not using the optimizer, the compiler needs the argument¬ 
passing registers for expression evaluation, so the arguments are copied to 
a local frame at function entry. 

When you are using the optimizer, the compiler attempts to keep register 
arguments in their original registers. 
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4.5 Interfacing C With Assembly Language 

There are three ways to use assembly language in conjunction with C code: 

□ Use separate modules of assembled code and link them with compiled C 
modules (see subsection 4.5.1, page 4-22). This is the most versatile 
method. 

□ Use inline assembly language, embedded directly in the C source (see 
subsection 4.5.3, page 4-28). 

□ Modify the assembly language code that the compiler produces. 

I-1 

Note: Assembler Support for Runtime Models 

The two argument-passing runtime models use different function structure 
and calling conventions. Assembly language functions called by C need to 
retrieve arguments according to the runtime model that was used to compile 
the code. The compiler and assembler provide support for the two runtime 
models in the form of two predefined symbols. The assembler symbol 
.REGPARM is set to 1 when -mr is used and is set to 0 otherwise. The 
compiler symbol _REGPARM is defined to be 1 if -mr is used and is set to 
0 otherwise. Example 4-1 on page 4-25 shows how to use these symbols 
to write code that will work with either runtime model. 

I_I 

4.5.1 Assembly Language Modules 

Interfacing with assembly language functions is straightforward if you follow 
the calling conventions defined in Section 4.4 and the register conventions 
defined in Section 4.3. C code can access variables and call functions defined 
in assembly language, and assembly code can access C variables and call 
C functions. Follow these guidelines to interface assembly language and C: 

□ All functions, whether they are written in C or assembly language, must 
follow the conventions outlined in Section 4.3, page 4-11. 

□ You must preserve any dedicated registers modified by a function. 
(You must preserve the DP in the small model only.) These are the 
dedicated registers: 


Save as integers 

Save as floating-point 

R4 

RS R6 R7 

AR4 

AR5 

AR6 

AR7 

FP 

DP (small model only) 

SP 

R8 (‘C4x only) 
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All registers are saved as integers except R6 and R7, which are saved as 
floating-point values. If the SP is used normally, it does not need to be 
explicitly preserved. In other words, the assembly function is free to use 
the stack as long as anything that is pushed is popped back off before the 
function returns (thus preserving SP). 

All other registers (such as expression registers, index registers, status 
registers, and block repeat registers) are not dedicated and can be used 
freely without first being saved. 

□ Interrupt routines must save the registers they use. Registers R0-R7 
(R0-R11 on the TMS320C4x) must be saved as complete 40-bit values 
because they may contain either integers or floating-point values when 
the interrupt occurs. For more information about interrupt handling, refer 
to Section 4.6 on page 4-30. 

□ Access arguments from the stack or in the designated registers, depend¬ 
ing on which argument-passing model is used. 

□ When calling a C function from assembly language, follow the guidelines 
in subsection 4.4.1, on page 4-16; push the arguments on the stack in 
reverse order. When using the register-argument model, load the 
designated registers with arguments, and push the remaining arguments 
on the stack as described in subsection 4.4.2, on page 4-17. When calling 
C functions, remember that only the dedicated registers are preserved. C 
functions can change the contents of any other register. 

□ Functions must return values correctly according to their C declarations. 
Integers, pointers, and floating-point values are returned in register R0, 
and structures are returned as described in step 4 on page 4-20. 

□ No assembly module should use the .cinit section for any purpose other 
than autoinitialization of global variables. The C startup routine in 
boot.asm assumes that the .cinit section consists entirely of initialization 
tables. Disrupting the tables by putting other information in .cinit can cause 
unpredictable results. 

□ The compiler appends an underscore (_) to the beginning of all identifiers. 
In assembly language modules, you must use a prefix of _ for all objects 
that are to be accessible from C. For example, a C object named x is called 
_x in assembly language. For identifiers that are to be used only in an 
assembly language module or modules, any name that does not begin 
with a leading underscore may be safely used without conflicting with a C 
identifier. 
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□ Any object or function declared in assembly that is to be accessed or called 
from C must be declared with the global directive in the assembler. This 
defines the symbol as external and allows the linker to resolve references 
to it. 

Likewise, to access a C function or object from assembly, declare the C 
object with .global. This creates an undefined external reference that the 
linker will resolve. 

Predefined Symbols 


The assembler has several predefined symbols that allow you to write 
assembly code that is compatible with the different runtime models. You can 
conditionally assemble code corresponding to different models by using these 
symbols as control switches when you invoke the assembler with the 
appropriate options (this happens automatically when you use c!30): 


Symbols 

Value 

Description 

.TMS320C30 

1 orO 

1 if -v30 option used 

.TMS320C40 

1 orO 

1 if -v40 option used 

.REGPARM 

1 orO 

1 if -mr option used 

.BIGMODEL 

1 orO 

1 if -mb option used 


An Example of an Assembly Language Function 

Example 4-1 illustrates a C function called main, which calls an assembly 
language function called asmfunc. The asmfunc function takes its single 
argument, adds it to the C global variable called gvar, and returns the result. 
Note that this example can be used with either of the argument-passing 
conventions. 

In the assembly language code in Example 4-1, note the underscores on all 
the C symbol names. Note also how the DP must be set only when accessing 
global variables in the big model. For the small model, the LDP instruction can 
be omitted. To use this example with either the large or small model, use the 
predefined symbol .BIGMODEL to conditionally assemble the LDP statement. 
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Example 4-1. An Assembly Language Function Called From C 


(a) C Program 


extern int asmfunc (); 

/* declare extern asm function 

*/ 

int gvar; 

/* define global variable 

*/ 

main() 



1 

int i; 



i = asmfunc(i); 

} 

/* call function normally 

*/ 

(b) Assembly Language Program 

FP .set AR3 

; FP is AR3 


.global _asmfunc 

; Declare external function 


.global _gvar 

; Declare external variable 


_asmfunc: 



.if .REGPARM = 0 

; standard runtime model 


PUSH FP 

; Save old FP 


LDI SP, FP 

; Point to top of stack 


LDI *—FP(2),AR2 

; Load argument into AR2 


.endif 

; Both runtime models 


.if .BIGMODEL 



LDP _gvar 

; Set DP to page of gvar 


.endif 

;(BIG MODEL ONLY) 


LDI @_gvar, RO 



ADD I AR2 , RO 

; RO = gvar + argument 


if .REGPARM = 0 

; Standard runtime model 


POP FP 

;Restore FP 



.endif 
RETS 


In the C program in Example 4-1, the extern declaration of asmfunc is optional 
because the function returns an int. Like C functions, assembly functions need 
be declared only if they return noninteger values. If you are using the 
register-argument runtime model, all functions, including assembly language 
functions, should have prototypes so that the arguments are passed correctly. 


4.5.2 Accessing Assembly Language Variables From C 

It is sometimes useful for a C program to access variables or constants defined 
in assembly language. There are three different methods that you can use to 
accomplish this, depending on where and how the item is defined; a variable 
defined in the .bss section, a variable not defined in the .bss section, or a 
constant. 
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Accessing Variables Defined in the .bss Section 

Accessing uninitialized variables from the .bss section is straightforward: 

□ Use the .bss directive to define the variable. 

□ Use the .global directive to make the definition external. 

□ Remember to precede the name with an underscore. 

□ In C, declare the variable as extern, and access it normally. 

Example 4-2 shows an example that accesses a variable defined in .bss. 

Example 4-2. Accessing a Variable Defined in .bss From C 


(a) Assembly Language Program 


* Note the 

use of 

underscores in 

the 

following lines 

. bss 

_var 

1 ; Define 

the 

variable 

.global 

_var 

; Declare 

it 

as external 


(b) C Program 


extern int var; 

/* 

External variable 

*/ 

var = 1; 

/* 

Use the variable 

*/ 


Accessing Variables Not Defined in the .bss Section 

It is more difficult to access a variable from C when the variable is not defined 
in the .bss section and you are using the small memory model andVne variable 
is not allocated on the same data page as the .bss sections generated by the 
compiler. Note that using the big memory model causes the compiler to load 
the data page pointer prior to each direct memory access to variables; 
therefore, the following method is not needed. 

Consider a lookup table, defined in assembly, that you do not want to put in 
RAM. In this case, you must define a pointer to the object and access it 
indirectly from C. 

The first step is to define the object. You can define the object in its own section 
(either initialized or uninitialized), or you can define it in an existing section. 
After defining the object, declare a global label that points to the beginning of 
the object. 

If the object has its own section, it can easily be linked anywhere into the 
memory space (this task is a little more difficult if the object is sharing an exist¬ 
ing section). To access it in C, you must declare an additional C variable to 
point to the object. Initialize the pointer with the assembly language label 
declared for the object; remember to remove the underscore. 
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I-1 

Note: Use the -mf Option When Using the Optimizer 

The optimizer, by default, assumes that all variables are defined in the .bss 
section. As a result of this assumption, the optimizer is free to change indirect 
memory accesses to direct ones if it is more efficient to do so. If you are 
accessing a variable that is not defined in .bss, this assumption is invalid. Use 
the -mf option to force the optimizer to preserve indirect memory access. 

I_I 

Example 4-3 shows an example for accessing a variable that is not defined 
in .bss. 

Example 4-3. Accessing a Variable Not Defined in .bss From C 


(a) Assembly Language Program 


.global 

_sine 

; Declare variable as external 

. sect 

"sine_tab" 

; Make a separate section 

_sine: 


; The table starts here 

.float 

o 

o 


.float 

0.015987 


.float 

0.022145 


(b) C Program 

extern float 

sine[]; / 

* This is the object */ 

float *sine_p 

= sine; / 

* Declare pointer to it */ 

f = sine_p[4] 

; /* 

Access sine as normal array */ 


A reference such as sine[4] will not work because the object is not in .bss and 
because a direct reference such as this generates incorrect code. 


Alternatively, the following can be used in C: 

extern float sine; 
float * sine_p = Ssine; 
f = sine_p[4]; 

or the following can be used in the assembly program: 

.global _sine 

_sine .usect "sine_tab", 4 


or 


.global _sine 
.bss _sine, 4 


In the last case, use the C method only if the .bss section generated by the 
assembler is not allocated (by the linker) on the same data page as the .bss 
output section generated by the compiler. 
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Accessing Assembly Language Constants 

You can define global constants in assembly language by using the .set and 
.global directives or in a linker command file using a linker assignment 
statement. These constants are accessible from C, but it is not straightforward. 

For normal variables defined in C or assembly language, the symbol table 
contains the address of the value of the variable. For assembler constants, 
however, the symbol table contains the value of the constant. The compiler 
cannot tell which items in the symbol table are values and which are 
addresses. 

If you try to access an assembler (or linker) constant by name, the compiler 
attempts to fetch a value from the address represented in the symbol table. To 
prevent this unwanted fetch, you must use the & (address of) operator to get 
the value. In other words, if _x is an assembly language constant, its value in 
C is &x. 

You can use casts and #defines to ease the use of these symbols in your pro¬ 
gram, as in Example 4-4. 

Example 4-4. Accessing an Assembly Language Constant From C 


(a) Assembly Language Program 


_table_size 

.set 10000 

; define the constant 


.global table size 

; make it global 


(b) C Program 


extern int table size; /* 

external 

ref 

*/ 

tdefine TABLE_SIZE ((int) 

(&table_size)) 


/* 

use cast 

to hide 

address-of */ 

for (i—0; i<TABLE_SIZE; ++i) 



/* 

use like 

normal 

symbol */ 


Because you are referencing only the symbol’s value as stored in the symbol 
table, the symbol’s declared type is unimportant. In Example 4-4, int is used. 
You can reference linker-defined symbols in a similar manner. 

4.5.3 Inline Assembly Language 
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A series of asm statements places sequential lines of assembly language into 
the compiler output with no intervening code. 

The asm statement is provided so that you can access features of the 
hardware that would be otherwise inaccessible from C. For example, you can 
modify the interrupt control registers to enable or disable interrupts. You can 
also access the status, interrupt enable, and interrupt flag registers. 

I-1 

Note: Avoid Disrupting the C Environment With asm Statements 

Be extremely careful not to disrupt the C environment with asm statements. 
The compiler does not check the inserted instructions. Inserting jumps and 
labels into C code can cause unpredictable results in variables manipulated 
in or around the inserted code. Directives that change sections or otherwise 
affect the assembly environment can also be troublesome. Be especially 
careful when you use the optimizer with asm statements. Although the 
optimizer cannot remove asm statements, it can significantly rearrange the 
code order near asm statements, possibly causing undesired results. The 
asm command is provided so that you can access features of the hardware, 
which, by definition, C is unable to access. 

i_i 

The asm statement is also useful for inserting comments in the compiler 
output; simply start the assembly code string with an asterisk (*) as shown 
below: 

asm("**** this is an assembly language comment"); 
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4.6 Interrupt Handling 

Interrupts can be handled directly with C functions by using a special naming 
convention: 

c_int nn 

nn is a two-digit interrupt number between 00 and 99. For example: 

cJntOI 

Using one of these function names defines an interrupt routine. When the 
compiler encounters one of these function names, it generates code that 
allows the function to be activated from an interrupt trap. 

Note that cJntOO is the C boot routine and should not be used as an interrupt 
routine. See Section 4.8 on page 4-36 for further information on this routine. 

A C interrupt routine is like any other C function in that it can have local 
variables and register variables; however, it should be declared with no 
arguments. Interrupt handling functions should not be called directly. 


4.6.1 Saving Registers During Interrupts 

When C code or assembly code is interrupted, all registers must be preserved, 
including the status registers. A problem arises with the extended-precision 
registers R0-R7 (R0-R11 on the ‘C4x): these registers can contain either 
integer or floating-point values, and an interrupt routine cannot determine the 
type of value in a register. Thus, an interrupt routine must preserve all 40 bits 
of any of these registers that it modifies. This involves saving both the integer 
part (lower 32 bits) and the floating-point part (upper 32 bits). 

The following code illustrates the entry and exit sequences for an interrupt ser¬ 
vice routine that has two local variables and uses registers FP, SP, ST, R3, R4, 


and AR4: 








PUSH 

FP 

; save 

old FP 





LDI 

SP, FP 

; set 

up new 

FP 




ADD I 

2, SP 

; allocate local frame 


PUSH 

ST 

; s a ve 

ST 





PUSH 

R3 

; save 

lower 

32 

bits 

of 

R3 

PUSHF 

R3 

; save 

upper 

32 

bits 

of 

R3 

PUSH 

R4 

; save 

lower 

32 

bits 

of 

R4 

PUSHF 

R4 

; s a ve 

upper 

32 

bits 

of 

R3 

PUSH 

AR4 

; s a ve 

AR4 
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Exit 


POP 

AR4 

; restore 

AR4 



POPF 

R4 

; restore 

upper 

32 bits of 

R4 

POP 

R4 

; restore 

lower 

32 bits of 

R4 

POPF 

R3 

; restore 

upper 

32 bits of 

R3 

POP 

R3 

; restore 

lower 

32 bits of 

R3 

SUB I 

2, SP 

; deallocate local frame 


POP 

FP 

; restore 

Frame 

Pointer 


POP 

reti 

ST 

; restore 

STatus 

register 



Notice how the upper and lower bits of R3 and R4 are saved and restored sep¬ 
arately. Any extended-precision register must be saved in two parts. All other 
registers can be saved as integers. 

4.6.2 Assembly Language Interrupt Routines 

Interrupts can also be handled with assembly language code, as long as the 
register conventions are followed. Like all assembly functions, interrupt 
routines can use the stack, access global C variables, and call C functions nor¬ 
mally. When calling C functions, be sure that all nondedicated registers are 
preserved because the C function can modify any of them. Of course, dedi¬ 
cated registers need not be saved because they are preserved by the C func¬ 
tion. Interrupt handler functions, whether in C or assembly, must be installed 
by placing their address in the interrupt vector table. On the TMS320C3x, this 
table is located in the first 64 words of the address space. On the TMS320C4x, 
the table can be located anywhere on any 512 word boundary in the address 
space. The IVTP register points to the location of the interrupt vector table. 
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4.7 Runtime-Support Arithmetic Routines 

The runtime-support library contains a number of assembly language func¬ 
tions that provide arithmetic routines for C math operators that the 
TMS320C3x/C4x instruction set does not provide, such as division. There are 
as many as three different versions of each of these functions. The versions 
are distinguished from each other by the number appended to the function 
name. For example, DIV_F30 is the version of DIV_F that is called when the 
code is compiled for the TMS320C3x, DIV_F40 is for the ‘C4x, and DIV_F is 
the version called by code compiled by version 4.10 (and all earlier versions) 
of the compiler. 

The TMS320C3x MPYI (multiply integer) instruction does not perform full 
32-bit multiplication (the TMS320C4x MPYI instruction does); it uses only the 
lower 24 bits of each operand. Because standard C requires full 32-bit 
multiplication, a runtime-support function, MPYJ30, is provided to implement 
32-bit integer multiplication for the TMS320C3x. This function does not follow 
the standard C calling sequence; instead, operands are passed in registers RO 
and R1. The 32-bit product is returned in RO. 

Note that using the shell option -mp causes the code generator to inline 32-bit 
by 32-bit and 32-bit by 16-bit integer multiplication, rather than call MPYJ30. 
Inlining this multiplication significantly reduces cycle time. In addition, the 
MPYJ30 function is not used for squares (such as i * i); an inline squaring func¬ 
tion is used, which also reduces cycle time. 

The compiler uses the TMS320C3x MPYI instruction only in cases where 
address arithmetic is performed (such as during array indexing); because no 
address can have more than 24 bits, a 24 x 24 multiply is sufficient. You can 
use the -mm option to force the compiler to use MPYI instructions for all integer 
multiplies. 

Because the TMS320C4x MPYI instruction performs full 32-bit multiplication, 
there is no MPYJ40 function. 

Because the TMS320C3x/C4x has no division instructions, integer and 
floating-point division are performed via calls to additional runtime-support 
functions named DIVJ30 and DIV_F30 (or DIVJ40 and DIV_F40 for the 
TMS320C4x). Another function, MOD_I30, performs the integer modulo 
operation. Corresponding functions named DIVJJ30 and MODJJ30 are used 
for unsigned integer division and modulo. Like MPYJ30, these functions take 
their arguments from RO and R1 and return the result in RO. These functions 
differ for the TMS320C3x and the TMS320C4x because the ‘C4x division func¬ 
tions take advantage of the RCPF instruction (16-bit reciprocal). 
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There are three runtime-support arithmetic functions specifically for extended- 
precision arithmetic: MPY_LD (multiply), DIV_LD (divide), and INV_LD 
(inverse/reciprocals). These functions support the 40-bit long double data 
type. 

The runtime-support arithmetic functions can use expression registers without 
saving them. Each function has individual register-use conventions, and the 
compiler respects these conventions. Register use is fully documented in the 
source to each of the functions. 

The arithmetic functions are written in assembly language. Because of the 
special calling conventions these functions use, you cannot access them 
from C. 

Object code for them is provided in any of the runtime object libraries provided 
(listed in Section 2.3 on page 2-35). Any of these functions that your program 
needs are linked in automatically if you name one of these libraries as input 
at link time. 

The source code for these functions is provided in the source library rts.src. 
The source code has comments that describe the operation and timing of the 
functions. You can extract, inspect, and modify any of the math functions; be 
sure you follow the special calling conventions and register-saving rules out¬ 
lined in this section. 

Table 4-4 summarizes the runtime-support functions used for arithmetic. 
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Table 4-4. Summary of Runtime-Support Arithmetic Functions 


Function 

Description 

Defined In 

Registers Used 

MPYJ30 

Integer multiply 

mpyi.asm 

RO, R1, ARO, AR1 

MPY_K30 

Integer multiply by constant 

mpyk.asm 

RO, R1, ARO, AR1 

MPY_LD 

40-bit float multiply 

mpyld.asm 

RO, R1, R2, R3, BK 

DIVJ30 

Integer divide 

divi.asm 

RC, RS, RE 

DIV_I40 

Integer divide 

divi.asm 

RC, RS, RE 

DIV_U30 

Unsigned integer divide 

divu.asm 

RO, R1, ARO, AR1, RC, RS, RE 

DIV_U40 

Unsigned integer divide 

divu.asm 

RO, R1, ARO, AR1, RC, RS,RE 

DIVF30 

Floating-point divide 

divf.asm 

RO, R1, ARO, AR1 

DIVF40 

Floating-point divide 

divf.asm 

RO, R1, ARO, AR1, RIO 

DIV_LD 

40-bit float divide 

divld.asm 

RO, R1, R2, R3, R5, RC, BK 

INVF30 

Floating-point reciprocal 

invf.asm 

RO, R1, ARO, AR1 

INV_F40 

Floating-point reciprocal 

invf.asm 

RO, R1, ARO, AR1 

INV_LD 

40-bit float reciprocal 

invld.asm 

RO, R1, R2, R3, BK 

MODJ30 

Integer modulo 

modi.asm 

RO, R1, ARO, AR1 

MODJ40 

Integer modulo 

modi.asm 

RO, R1, ARO, AR1 

MOD _U30 

Unsigned integer modulo 

modu.asm 

RO, R1, ARO, AR1, RC, RS, RE 

MODU40 

Unsigned integer modulo 

modu.asm 

RO, R1, ARO, AR1, RC, RS,RE 

Functions Provided for Compatibility With Previous Compiler Versions 

MPYJ 

Integer multiply 

arith410.asm 

R0-R3 

MPY_X 

Integer multiply for early 
versions of ’C30 

arith410.asm 

R0-R3 

DIVJ 

Integer divide 

arith410.asm 

R0-R3, RC, RS, RE 

DIV_U 

Unsigned integer divide 

arith410.asm 

R0-R3, RC, RS, RE 

DIVF 

Floating-point divide 

arith410.asm 

R0-R3 

MODJ 

Integer modulo 

arith410.asm 

R0-R3, RC, RS, RE 

MOD _U 

Unsigned integer modulo 

arith410.asm 

R0-R3, RC, RS, RE 
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4.7.1 Precision Considerations 

The compiler will replace costly mathematical operations with narrower 
precision equivalents if the containing expression does not require the use of 
high-precision functions. For example, on the ’C3x, if the outermost operation 
causes the precision of the entire expression to be limited to 24 bits or less, 
all multiplies within the expression will be performed with the MPYI instruction 
instead of with the MPYJ30 function. Bit masks and shift counts may be 
reduced to fit within an immediate value rather than requiring a space in the 
constant table. 

For example, consider the following code fragment: 

int offset, index, i, j , k, 1, m, n, o; 

i = OxFFF & (offset * index); 
j = (offset * index) << 12; 
k = (OxOOFFFFFF & offset) << 24; 

1 = array[OxFF & (offset * index)]; 
m = array[ (offset * index) << 12]; 
n = array[(OxFFFFFF & offset) << 24]; 
o = (OxFFFFFFF & (offset * index)) << 24; 

In all of the cases above, the compiler recognizes that the interior 
multiplications will be precision-limited by the various masks and/or shifts spe¬ 
cified. It will then avoid using the MPYJ30 runtime support function, even 
though the variables offset and index are 32-bit integers. The MPYI instruction 
or a series of shifts will be used instead. In the assignment of variable o, the 
precision requirements introduced by the shift left of 24 allow the compiler to 
convert the value OxFFFFFFF into OxFF, eliminating the need to store this val¬ 
ue on the constant table. 
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4.8 System Initialization 

Before you can run a C program, the C runtime environment must be created. 
This task is performed by the C boot routine, which is a function called cJntOO. 

The cJntOO function can be branched to, called, or vectored by reset hardware 
to begin running the system. The function is in the runtime-support library and 
must be linked with the other C object modules. This occurs automatically 
when you use the -c or -cr option in the linker and include a runtime-support 
library created from rts.src as one of the linker input files. When C programs 
are linked, the linker sets the entry point value in the executable output module 
to the symbol cJntOO. 

The cJntOO function performs the following tasks in order to initialize the 
C environment: 

□ Defines a section called .stack for the system stack and sets up the initial 
stack and frame pointers 

□ Autoinitializes global variables by copying the data from the initialization 
tables in .cinit to the storage allocated for the variables in .bss. In the small 
model, the constant tables are also copied from .cinit to .bss. Note this 
does not refer to data in the .const section 

In the RAM initialization model, a loader performs this step before the 
program runs (it is not performed by the boot routine). For more 
information, refer to subsection 4.8.1. 

□ Small memory model only — sets up the page pointer DP to point to the 
global storage page in .bss 

□ Calls the function main to begin running the C program 

You can replace or modify the boot routine to meet your system requirements. 
However, the boot routine must perform the four operations listed above in 
order to correctly initialize the C environment. The runtime-support source 
library contains the source to this routine in a module named boot.asm. 

4.8.1 Autoinitialization of Variables and Constants 

Some global variables must have initial values assigned to them before a 
C program starts running. The process of retrieving these variables’ data and 
initializing the variables with the data is called autoinitialization. 

The compiler builds tables in a special section called .cinit that contains data 
for initializing global and static variables. Each compiled module contains 
these initialization tables. The linker combines them into a single table (a single 
.cinit section). The boot routine uses this table to initialize all the variables that 
need values before the program starts running. 
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I-1 

Note: Initializing Variables 

In standard C, global and static variables that are not explicitly initialized are 
set to 0 before program execution. The TMS320C3x/C4x C compiler does 
not perform any preinitialization of uninitialized variables. Any variable that 
must have an initial value of 0 must be explicitly initialized. An alternative is 
to have a loader or boot.obj clear the .bss section before the program starts 
running. 


In the small memory model, any tables of long constant values or constant 
addresses must also be copied into the global data page at this time. Data for 
these tables is incorporated into the initialization tables in .cinit and thus is 
automatically copied at initialization time. 

There are two methods for copying the initialization data into memory: RAM 
and ROM. The RAM model of initialization is discussed on page 4-38; the ROM 
model of initialization is discussed on page 4-39. 


Initialization Tables 


The tables in the .cinit section consist of initialization records with varying 
sizes. Each initialization record has the following format: 

Figure 4-3. Format of Initialization Records in the .cinit Section 


.cinit Section 


Initialization Record 1 
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Initialization Record 

Initialization Record 3 
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Initialization Record n 


□ The first field (word 0, record 1) is the size (in words) of the initialization 
data for the variable. 

□ The second field (word 1, record 2) is the starting address of the area in 
the .bss section into which the initialization data must be copied. (This field 
points to a variable’s space in .bss.) 

□ The third field (word 2, record 3, through n) contains the data that is copied 
into the variable to initialize it. 
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The .cinit section contains an initialization record for each variable that must 
be initialized. For example, suppose two initialized variables are defined in C 
as follows: 

int i = 23; 

int a [ 5 ] = { 1, 2, 3, 4, 5 }; 

The initialization tables would appear as follows: 

.sect ".cinit" ; Initialization section 

* Initialization record for variable i 

.word 1 ; Length of data (1 word) 

.word _i ; Address in .bss 

.word 23 ; Data to initialize i 

* Initialization record for variable a 

.word 5 ; Length of data (5 words) 

.word _a ; Address in .bss 

.word 1,2,3,4,5 ; Data to initialize a 

The .cinit section contains only initialization tables in this format. If you are 
interfacing assembly language modules to your C program, do not use the 
.cinit section for any other purpose. 

When you link a program with the-c or-cr option, the linker links together the 
.cinit sections from all the C modules and appends a null word to the end of 
the entire section. This appears as a record with a size field of 0 and marks the 
end of the initialization tables. 

Initializing Variables in the RAM Model 

The RAM model, specified with the -cr linker option, allows variables to be 
initialized at load time instead of at runtime. This can enhance performance 
by reducing boot time and by saving the memory used by the initialization 
tables. 

The RAM option requires the use of a smart loader to perform the initialization 
as it copies the program from the object file into memory. 

In the RAM model, the linker marks the .cinit section with a special attribute 
(STYP_CPY equals 1). This means that the section is not loaded into memory 
and does not occupy space in the memory map. The linker also sets the sym¬ 
bol cinit to -1 to indicate to the C boot routine that the initialization tables are 
not present in memory; accordingly, no runtime initialization is performed at 
boot time. 

Instead, when the program is loaded into memory, the loader must detect the 
presence of the .cinit section and its special attribute. Instead of loading the 
section into memory, the loader uses the initialization tables directly from the 
object file to initialize the variables in .bss. To use the RAM model, the loader 
must understand the format of the initialization tables so that it can use them. 
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A loader is not part of the compiler package. The loader used in Tl emulator 
and simulator products is a smart loader. 

Figure 4-4. RAM Model of Autoinitialization 


Object File Memory 



Initializing Variables in the ROM Model 

The ROM model is the default model for autoinitialization. To use the ROM 
model, invoke the linker with the -c option. 

Under this method, the .cinit section is loaded into memory (possibly ROM) 
along with all the other sections, and global variables are initialized at runtime. 
The linker defines a special symbol called cinit that points to the beginning of 
the initialization tables in memory. When the program begins running, the C 
boot routine copies data from the tables (pointed to by cinit) into the specified 
variables in .bss. This allows initialization data to be stored in ROM and then 
copied to RAM each time the program is started. 
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Figure 4-5 


ROM Model of Autoinitialization 
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Runtime-Support Functions 


Some of the tasks that a C program must perform (such as I/O, floating-point 
arithmetic, dynamic memory allocation, string operations, and trigonometric 
functions) are not part of the C language itself. The runtime-support functions, 
which are included with the C compiler, are standard ANSI functions that 
perform these tasks. The runtime-support library, rts.src, contains the source 
for these functions, as well as for other functions and routines. If you use any 
of the runtime-support functions, be sure to build the appropriate library, 
according to the desired runtime model, using the library-build utility; then 
include that library as linker input when you link your C program. 

These are the topics covered in this chapter: 


Topic 


Page 
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Header Files. 
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5.1 Runtime-Support Libraries 

Nine runtime-support libraries are included with the TMS320C3x/C4x C 
compiler: eight object libraries containing object code for the runtime-support 
and a source library containing source code for the functions in the object 
libraries. 


Runtime Library 

Processor 

Option(s) Used 

rts30.lib 

TMS320C3X 

-mf -mi -o2 -x 

rts30g.lib 

TMS320C3X 

-mf -mi -o2 -x -g 

rts30r.lib 

TMS320C3X 

-mf -mi -o2 -x -mr 

rts30gr.lib 

TMS320C3X 

-mf -mi -o2 -x -g -mr 

rts40.lib 

TMS320C4X 

X 

1 

CM 

o 

1 

I 

1 

E 

l 

o 

■'t 

T 

rts40g.lib 

TMS320C4X 

O) 

1 

X 

1 

CM 

O 

1 

I 

1 

E 

1 

o 

■M- 

T 

rts40r.lib 

TMS320C4X 

-v40 -mf -mi -o2 -x -mr 

rts40gr.lib 

TMS320C4X 

E 

i 

O) 

i 

X 

1 

CM 

O 

1 

I 

1 

E 

l 

o 

■M- 

T 


rts.src is the source library. If necessary, you can create your own runtime- 
support library from rts.src by using the library-build utility (mk30) described 
in Chapter 6. 

All object libraries built from rts.src include the standard C runtime-support 
functions described in this chapter, the intrinsic arithmetic routines described 
in Section 4.7 on page 4-32, and the system startup routine, _c_int00. The 
object libraries are built from the C and assembly source contained in rts.src. 

When you link your program, you must specify an object library as one of the 
linker input files so that references to runtime-support functions can be 
resolved. You should usually specify libraries last on the linker command line 
because the assembler searches for unresolved references when it 
encounters a library on the command line. You can also use the -x linker option 
to force repeated searches of each library until it can resolve no more 
references. When a library is linked, the linker includes only those library mem¬ 
bers required to resolve undefined references. For more information about 
linking, refer to Section 2.10 on page 2-65. 
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5.1.1 Modifying a Library Function 

You can inspect or modify library functions by using the archiver to extract the 
appropriate source file or files from rts.src. For example, the following 
command extracts two source files: 

ar30 x rts.src atoi.c strcpy.c 

To modify a function, extract the source as in the previous example. Make the 
required changes to the code, recompile, and then reinstall the new object file 
or files into the library: 

cl30 -options atoi.c strcpy.c ; recompile 

ar30 r rts.lib atoi.obj strcpy.obj ;rebuild library 

You can also build a new library this way, ratherthan rebuilding back into rts.lib. 
For more information about the archiver, refer to Chapter 8 of the 
TMS320C3x/C4x Assembly Language Tools User’s Guide. 

5.1.2 Building a Library With Different Options 

You can create a new library from rts.src by using the library-build utility, mk30. 
For example, use this command to build an optimized runtime-support library 
for the TMS320C4x using the big memory model and the register-argument 
runtime model: 

mk.30 —u -mr -v40 -mb -o2 -x rts.src -1 rts40rb.lib 

The -u option tells the mk30 utility to use the header files in the current 
directory, ratherthan extracting them from the source archive. The new library 
is compatible with any code compiled for the ’C4x (- v40) using the big memory 
model (-mb) and the register-argument runtime model (-mr). The use of the 
optimizer (-o2) and inline function expansion (-x) options does not affect 
compatibility with code compiled without these options. 
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5.2 Header Files 


Each runtime-support function is declared in a header file. Each header file 
declares the following: 


□ A set of related functions (or macros) 

□ Any types that you need to use the functions 

□ Any macros that you need to use the functions 


These are the header files that declare the runtime-support functions: 


assert.h 
ctype.h 
errno.h 
file . h 
float. h 


limits.h 
math.h 
set jmp.h 
stdarg.h 
stddef.h 


stdio.h 
stdlib.h 
string.h 
time.h 


In order to use a runtime-support function, you must first use the #include 
preprocessor directive to include the header file that declares the function. For 
example, the isdigit function is declared by the ctype.h header. Before you can 
use the isdigit function, you must first include ctype.h: 

#include <ctype.h> 


val = isdigit(num); 

You can include headers in any order. You must include a header before you 
reference any of the functions or objects that it declares. 

Subsections 5.2.1 through 5.2.7 describe the header files that are included 
with the TMS320C3x/C4x C compiler. Section 5.3, page 5-13, lists the 
functions that these headers declare. 

5.2.1 Diagnostic Messages (assert.h) 

The assert.h header defines the assert macro, which inserts diagnostic failure 
messages into programs at runtime. The assert macro tests a runtime 
expression. 

□ If the expression is true (nonzero), the program continues running. 

□ If the expression is false, the macro outputs a message that contains the 
expression, the source file name, and the line number of the statement 
that contains the expression; then, the program terminates (via the abort 
function). 

The assert.h header refers to another macro named NDEBUG (assert.h does 
not define NDEBUG). If you have defined NDEBUG as a macro name when 
you include assert.h, then assert is turned off and does nothing. If NDEBUG 
is not defined, assert is enabled. 


5-4 


Header Files 


5.2.2 Character-Typing and Conversion (ctype.h) 

The ctype.h header declares functions that test and convert characters. 

For example, a character-typing function may test a character to determine 
whether it is a letter, a printing character, a hexadecimal digit, etc. These 
functions return a value of true (a nonzero value) or false (0). 

The character-conversion functions convert characters to lower case, upper 
case, or ASCII and return the converted character. 

Character-typing functions have names in the form isxxx(for example, isdigit). 
Character-conversion functions have names in the form toxxx (for example, 
touppef). 

The ctype.h header also contains macro definitions that perform these same 
operations; the macros run faster than the corresponding functions. The typing 
macros expand to a lookup operation in an array of flags (this array is defined 
in ctype.c). The macros have the same name as the corresponding functions, 
but each macro is prefixed with an underscore (for example, Jsdigit). 

5.2.3 Error Reporting (errno.h) 

Errors can occur in a math function if the invalid parameter values are passed 
to the function or if the function returns a result that is outside the defined range 
for the type of the result. When this happens, a variable named errno is set to 
the value of one of the following macros: 

□ EDOM, for domain errors (invalid parameter) 

□ ERANGE, for range errors (invalid result) 

C code that calls a math function can read the value of errno to check for error 
conditions. The errno variable is declared in errno.h and defined in errno.c. 

5.2.4 Low-Level I/O Functions (file.h) 

The file.h header declares the low-level I/O functions used to implement input 
and output operations. 

The C I/O functions make it possible to access the host’s operating system to 
perform I/O (using the debugger). For example, printf statements executed in 
a program appear in the debugger command window. When used in 
conjunction with the debugging tools, the capability to perform I/O on the host 
gives you more options when debugging and testing code. 

For detailed information on using the low-level I/O functions, see Appendix B. 
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5.2.5 Limits (float.h and limits.h) 

The float.h and limits.h headers define macros that expand to useful limits and 
parameters of the TMS320C3x/C4x numeric representations. Table 5-1 and 
Table 5-2 list these macros and the limits with which they are associated. 

Table 5-1. Macros That Supply Integer Type Range Limits ( limits.h ) 


Macro 

Value 

Description 

CHAR_BIT 

32 

Number of bits in type char 

SCHAR_MIN 

-2147483648 

Minimum value for a signed char 

SCHAR_MAX 

2147483647 

Maximum value for a signed char 

UCHAR_MAX 

4294967295 

Maximum value for an unsigned char 

CHAR_MIN 

SCHARJVIIN 

Minimum value for a char 

CHAR_MAX 

SCHAR_MAX 

Maximum value for a char 

SHRTJVIIN 

-2147483648 

Minimum value for a short int 

SHRTJVIAX 

2147483647 

Maximum value for a short int 

USHRT_MAX 

4294967295 

Maximum value for an unsigned short int 

INTMIN 

-2147483648 

Minimum value for an int 

INTJVIAX 

2147483647 

Maximum value for an int 

UINTMAX 

4294967295 

Maximum value for an unsigned int 

LONG_MIN 

-2147483648 

Minimum value for a long int 

LONG_MAX 

2147483647 

Maximum value for a long int 

ULONGJVIAX 

4294967295 

Maximum value for an unsigned long int 


Note: Negative values in this table are defined as expressions in the actual header file so that 
their type is correct. 
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Table 5-2. Macros That Supply Floating-Point Range Limits (float.h) 


Macro 

Value 

Description 

FLT_RADIX 

2 

Base or radix of exponent representation 

FLT_ROUNDS 

-1 

Rounding mode for floating-point 
addition 

FLT DIG 

6 

Number of decimal digits of precision for 

DBL DIG 

6 

a float, double, or long double 

LDBL_DIG 

8 


FLT MANT DIG 

24 

Number of base-FLT RADIX digits in the 

DBL MANT DIG 

24 

mantissa of afloat, double, orlong double 

LDBLJMANTDIG 

32 


FLT MIN EXP 

-126 

Minimum negative integer such that 

DBL MIN EXP 


FLT RADIX raised to that power minus 1 

LDBL_MIN_EXP 


is a normalized float, double, or long 
double 

FLT MAX EXP 

128 

Maximum negative integer such that 

DBL MAX EXP 


FLT RADIX raised to that power minus 1 

LDBL_MAX_EXP 


is a representable finite float, double, or 
long double 

FLT EPSILON 

1.1920929E-07 

Minimum positive float, double, or long 

DBL EPSILON 

1.1920929E-07 

double number xsuch that 1.0 + x* 1.0 

LDBL_EPSILON 

1.19209287E-0 7 


FLT MIN 

5.8774817E-39 

Minimum positive float, double, or long 

DBL MIN 

5.8774817E-39 

double 

LDBL_MIN 

5.87747175E-39 


FLT MAX 

3.4028235E+38 

Maximum float, double, or long double 

DBL MAX 

3.4028235E+38 

LDBLJMAX 

3.40282367E+38 


FLT MIN 10 EXP 

-39 

Minimum negative integers such that 10 

DBL MIN 10 EXP 


raised to that power is in the range of 

LDBL_MIN_10_EXP 


normalized floats, doubles, or long 
doubles 

FLT MAX 10 EXP 

38 

Maximum positive integers such that 10 

DBL MAX 10 EXP 


raised to that power is in the range of 

LDBL MAX 10 EXP 


representable finite floats, doubles, or 
long doubles 


Key to prefixes: 

FLT_ applies to type float 

DBL_ applies to type double 

LDBL_ applies to type long double 
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5.2.6 Floating-Point Math (math.h) 

The math.h header defines several trigonometric, exponential, and hyperbolic 
math functions. These math functions expect double precision floating point 
arguments and return double precision floating point values. Except where 
indicated, all trigonometric functions use angles expressed in radians. 

The math.h header also defines one macro named HUGE_VAL; the math 
functions use this macro to represent out-or-range values. When a function 
produces a floating-point return value that is too large to be represented, it 
returns HUGE_VAL instead. 

5.2.7 Nonlocal Jumps (setjmp.h) 

The setjmp.h header defines one type, one macro, and one function for 
bypassing the normal function call and return discipline. These include: 

□ j mpbuf, an array type suitable for holding the information needed to 
restore a calling environment. 

□ setjmp, a macro that saves its calling environment in its jmp_buf argument 
for later use by the longjmp function. 

□ longjmp, a function that uses its jmp_buf argument to restore the program 
environment. 

5.2.8 Variable Arguments (stdarg.h) 

Some functions can have a variable number of arguments whose types can 
differ; such functions are called variable-argument functions. The stdarg.h 
header declares three macros and a type that help you to use variable- 
argument functions: 

□ The three macros are va_start, va_arg, and va_end. These macros are 
used when the number and type of arguments may vary each time a 
function is called. 

□ The type, vajist, is a pointer type that can hold information for va_start, 
va_end, and va_arg. 

A variable-argument function can use the macros declared by stdarg.h to step 
through its argument list at runtime, when it knows the number and types of 
arguments actually passed to it. 

I-1 

Note: Variable-Argument Functions Must Have Prototypes 

A variable-argument function must have a prototype to ensure that the 
arguments are passed correctly. 

I_I 


5-8 




Header Files 


5.2.9 Standard Definitions (stddef.h) 

The stddef.h header defines two types and two macros. The types include: 

□ ptrdiff_t, a signed integer type that is the resul from the subtraction of two 
pointers 

□ size_t, an unsigned integer type that is the data type of the sizeof operator 

The macros include: 

□ The NULL macro, which expands to a null pointer constant(O) 

□ The offsetof(type, identifier) macro, which expands to an integer that has 
type size_t. The result is the value of an offset in bytes to a structure 
member (identifier) from the beginning of its structure (type) 

These types and macros are used by several of the runtime-support functions. 

5.2.10 stdio.h—I/O Functions 

The stdio.h header defines types and macros and declares functions. 


Type Declarations 


The following table lists the types defined in stdio.h: 


Type 

Description 

size_t 

An unsigned integer type that is the data type of the sizeof 
operator 

fpos_t 

An unsigned long type that can uniquely specify every position 
within a file 

FILE 

A structure type to record all the information necessary to control 
a stream 
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Macro Declarations 


The following table lists the macros defined in stdio.h: 


Macro 

Description 

NULL 

Expands to a null pointer constant(O). Originally defined in 
stddef.h. It is not redefined if it was already defined. 

BUFSIZ 

Expands to the size of the buffer that setbuff) uses 

EOF 

The end-of-file marker 

FOPEN_MAX 

Expands to the largest number of files that can be open at 
one time 

FILENAMEMAX 

Expands to the length of the longest file name in 
characters 

Ltmpnam 

Expands to the longest filename string that tmpnam() can 
generate 

SEEK CUR 

SEEK SET 
SEEK_END 

Expand to indicate the position (current, start-of-file, or 
end-of-file, respectively) in a file 

TMP_MAX 

Expands to the maximum number of unique filenames that 
tmpnamQ can generate 

stderr 

stdin 

stdout 

Pointers to the standard error, input, and output files, re¬ 
spectively 


5.2.11 General Utilities (stdlib.h) 

The stdlib.h header declares several functions, one macro, and two types. The 

macro is named RAND_MAX. The types include: 

□ div_t, a structure type that is the type of the value returned by the div 
function 

□ ldiv_t, a structure type that is the type of the value returned by the Idiv 
function 

The stdlib.h header also declares many of the common library functions: 

□ String conversion functions that convert strings to numeric 
representations 

□ Searching and sorting functions that allow you to search and sort arrays 

□ Sequence-generation functions that allow you to generate a 
pseudorandom sequence and allow you to choose a starting point for a 
sequence 
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□ Program-exit functions that allow your program to terminate normally or 
abnormally 

□ Integer-arithmetic that is not provided as a standard part of the C 
language 

5.2.12 String Functions (string.h) 

The string.h header declares standard functions that allow you to perform the 
following tasks with character arrays (strings): 

□ Move or copy entire strings or portions of strings 

□ Concatenate strings 

□ Compare strings 

□ Search strings for characters or other strings 

□ Find the length of a string 

In C, all character strings are terminated with a 0 (null) character. The string 
functions named strxxx all operate according to this convention. Additional 
functions that are also declared in string.h allow you to perform corresponding 
operations on arbitrary sequences of bytes (data objects), where a 0 value 
does not terminate the object. These functions have names such as memxxx. 

When you use functions that move or copy strings, be sure that the destination 
is large enough to contain the result. 

5.2.13 Time Functions (time.h) 

The time header declares one macro, several types, and functions that 
manipulate dates and times. Times are represented in two different ways: 

□ As an arithmetic value of type time_t. When expressed in this way, a time 
is represented as a number of seconds since 12:00 AM January 1, 1900. 
The time_t is a synonym for the type unsigned long. 

□ As a structure of type struct_tm. This structure contains members for 
expressing time as a combination of years, months, days, hours, minutes, 
and seconds. A time represented like this is called broken-down time. The 
structure has the following members. 


int 

tm_sec; 

/* 

seconds after the minute (0-59) 

*/ 

int 

tm_min; 

/* 

minutes after the hour (0-59) 

*/ 

int 

tm_hour; 

/* 

hours after midnight (0-23) 

*/ 

int 

tm_raday; 

/* 

day of the month (1-31) 

*/ 

int 

tm_mon; 

/* 

months since January (0-11) 

*/ 

int 

tm_year; 

/* 

years since 1900 (0-99) 

*/ 

int 

tm_wday ; 

/* 

days since Saturday (0-6) 

*/ 

int 

tm_yday; 

/* 

days since January 1 (0-365) 

*/ 

int 

tm_isdst; 

/* 

Daylight Savings Time flag 

*/ 


Runtime-Support Functions 


5-11 


Header Files 


A time, whether represented as a time_t or a struct tm, can be expressed from 
different points of reference. 

□ Calendar time represents the current Gregorian date and time. 

□ Local time is the calendar time expressed for a specific time zone. 

Local time may be adjusted for daylight savings time. Obviously, local time 
depends on the time zone. The time.h header declares a structure type called 
tmzone and a variable of this type called _tz. You can change the time zone 
by modifying this structure, either at runtime or by editing tmzone.c and 
changing the initialization. The default time zone is U.S. central standard time. 

The basis for all the functions in time.h are two system functions: clock and 
time. Time provides the current time (in time_t format), and clock provides the 
system time (in arbitrary units). The value returned by clock can be divided by 
the macro CLOCKS_PER_SEC to convert it to seconds. Since these functions 
and the CLOCKS_PER_SEC macro are system specific, only stubs are 
provided in the library. To use the other time functions, you must supply custom 
versions of these functions. 
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5.3 Summary of Runtime-Support Functions and Macros 


Refer to the following pages for information about functions and macros: 


Function or Macro 

Error Message Macro . 

Character-Typing Conversion Functions . 

Floating-Point Math Functions. 

Variable-Argument Functions and Macros 

General Utilities . 

String Functions . 

Setjmp Function and Longjmp Macro 
Time Functions. 


Page 

5-14 

5-14 

5-14 

5-15 

5-17 

5-19 

5-20 

5-19 
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Error Message Macro (assert.h) 

Description 

void assert(int expression);* 

Inserts diagnostic messages into programs 

Character-Typing Conversion 

Functions (ctype.h) 

Description 

int 

isalnum(char c);t 

Tests c to see if it’s an alphanumeric ASCII character 

int 

isalpha(char c);t 

Tests c to see if it’s an alphabetic ASCII character 

int 

isascii(char c);t 

Tests c to see if it’s an ASCII character 

int 

iscntrl(char c);t 

Tests c to see if it’s a control character 

int 

isdigit(char c);t 

Tests c to see if it’s a numeric character 

int 

isgraph(char c); t 

Tests c to see if it’s any printing character except a space 

int 

islower(char c); t 

Tests c to see if it’s a lowercase alphabetic ASCII character 

int 

isprint(char c);t 

Tests c to see if it’s a printable ASCII character (including spaces) 

int 

ispunct(char c);t 

Tests c to see if it’s an ASCII punctuation character 

int 

isspace(char c);t 

Tests c to see if it’s an ASCII spacebar, tab (horizontal or vertical), 
carriage return, formfeed, or newline character 

int 

isupper(char c);t 

Tests c to see if it’s an uppercase ASCII alphabetic character 

int 

isxdigit(char c);t 

Tests c to see if it’s a hexadecimal digit 

char 

toascii(char c);t 

Masks c into a legal ASCII value 

char 

tolower(int char c);t 

Converts c to lowercase if it’s uppercase 

char 

toupper(int char c);t 

Converts c to uppercase if it’s lowercase 

Floating-Point Math Functions (math.h) 

Description 

double 

acos(double x); 

Returns the arccosine of x 

double 

asin(double x); 

Returns the arcsine of x 

double 

atan(double x); 

Returns the arctangent of x 

double 

atan2(double y, double x); 

Returns the arctangent of y/x 

double 

ceil(double x);t 

Returns the smallest integer greater than or equal to x 

double 

cos(double x); 

Returns the cosine of x 

double 

cosh(double x); 

Returns the hyperbolic cosine of x 

double 

exp(double x); 

Returns the exponential function of x 

double 

fabs(double x);§ 

Returns the absolute value of x 

double 

floor(double x);t 

Returns the largest integer less than or equal to x 

double 

fmod(double x, double y);t 

Returns the floating-point remainder of x/y 

t 

Expands inline if -x is used 


* 

Macro 


§ 

Expands inline unless -xO is used 
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Floating-Point Math Functions 
(continued) 

Description 

double frexp(double value, int*exp); 

double ldexp(double x, int exp); 

Breaks value into a normalized fraction and an integer power of 2 

Multiplies x by an integer power of 2 

double log(double x); 

Returns the natural logarithm of x 

double Iog10(double x); 

double modf(double value, int *iptr); 

Returns the base-10 logarithm of x 

Breaks value into a signed integer and a signed fraction 

double pow(double x, double y); 

Returns x raised to the power y 

double sin(double x); 

Returns the sine of x 

double sinh(double x); 

Returns the hyperbolic sine of x 

double sqrt(double x); 

Returns the nonnegative square root of x 

double tan(double x); 

Returns the tangent of x 

double tanh(double x); 

Returns the hyperbolic tangent of x 

Variable-Argument Functions and 
Macros (stdarg.h) 

Description 

type va_arg(va_list ap);^ 

Accesses the next argument of type type in a variable-argument 
list 

void va_end(va_list ap);t 

void va_start(va_list ap);t 

Resets the calling mechanism after using va_arg 

Initializes ap to point to the first operand in the variable-argument 
list 

I/O Functions (stdio.h) 

Description 

void clearerr(FILE *p); 

Clears the EOF and error indicators for the stream that p points to 

int fclose(FILE *iop); 

Flushes the stream that iop points to and closes the file associated 
with that stream 

int feof(FILE *p); 

Tests the EOF indicator for the stream that p points to 

int ferror(FILE *p); 

Tests the error indicator for the stream that p points to 

int fflush(register FILE *iop); 

Flushes the I/O buffer for the stream that iop points to 

int fgetc(register FILE *fp); 

Reads the next character in the stream that fp points to 

int fgetpos(FILE *iop, fpos_t *pos); 

Stores the object that pos points to to the current value of the file 
position indicator for the stream that iop points to 

char *fgets(char *ptr, register int size, 
register FILE *iop); 

FILE *fopen(const char *file, 
const char *mode); 

Reads the next size minus 1 character from the stream that iop 
points to into array ptr 

Opens the file that file points to; mode points to a string describing 
how to open the file 


t Expands inline if -x is used 

t Macro 

§ Expands inline unless -xO is used 
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I/O Functions (continued) 

Description 

int fprintf(FILE *iop, const char ‘format, 

■■■); 

Writes to the stream that iop points to 

int fputc(int c, register FILE *fp); 

int fputs(const char *ptr, register FILE 

*iop); 

size_t fread(void *ptr, size_t size, 
size_t count, FILE *iop); 

FILE *freopen(const char ‘file, 
const char ‘mode, 
register FILE *iop); 

int fscanf(FILE *iop, const char *fmt, ...); 

int fseek(register FILE *iop, long offset, 
int ptrname); 

int fsetpos(FILE *iop, const fpos_t *pos); 

Writes a single character, c, to the stream that fp points to 

Writes the string pointed to by ptr; points to the stream pointed to 
by iop 

Reads from the stream pointed to by iop and stores the input to the 
array pointed to by ptr 

Opens the file that file points to using the stream that iop points to; 
mode points to a string describing how to open the file 

Reads from the stream pointed to by iop 

Sets the file position indicator for the stream pointed to by iop 

Sets the file position indicator for the stream that iop points to pos; 
the pointer pos must be a value from fgetpos() on the same stream 

long ftell(FILE *iop); 

Obtains the current value of the file position indicator for the 
stream that iop points to 

size_t fwrite(const void *ptr, size_t size, 
size_t count, register FILE *iop); 

int getc(FILE *p); 

int getchar(void); 

void perror(const char *s); 

int printf(const char ‘format, ...); 

Writes a block of data from the memory pointed to by ptr to the 
stream that iop points to 

A macro that calls fgetc() 

A macro that calls fgetc() and supplies stdin as the argument 

Maps the error number in s to a string and prints the error message 

Performs the same function as fprintf but uses stdout as its output 
stream 

int putc(int x, FILE *p); 

int putchar(int x); 

int puts(const char *ptr); 

int remove(const char ‘file); 

int rename(const char ‘old, 
const char ‘new); 

void rewind(register FILE *iop); 

A macro that performs like fputc() 

Writes a character to the standard output device 

Writes a string (pointed to by ptr) to the standard output device 

Makes the file pointed to by file no longer available by that name 

Renames the file pointed to by old to the name pointed to by new 

Sets the file position indicator for a stream to the beginning of the 
file pointed to by iop 

int scanf(const char ‘format, ...); 

void setbuf(register FILE *iop, char *buf); 

int setvbuf(register FILE *iop, 

register char *buf, register int type, 
register size t size); 

Reads the stream from the standard input device 

Specifies the buffer used by the stream pointed to by iop 

Defines and associates a buffer with a stream 
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I/O Functions (continued) Description 

Writes to the array pointed to by string 


int sprintf(char ‘string, 

const char *format, ...); 

int sscanf(const char *str, 

const char *format, ...); 

FILE ‘tmpfile(void); 

char *tmpnam(char *s); 

int ungetc(int c, FILE *p); 

int vfprintf(FILE *iop, const char ‘format, 
vajist ap); 

int vprintf(const char ‘format, vajist ap); 


Reads from the string pointed to by str 

Creates a temporary file 
Generates a string that is a valid filename 
Writes the character c to a stream pointed to by p 
Writes to the stream pointed to by iop. 

Writes to the standard output device 


int vsprintf(char ‘string, const char ‘format, Writes to the array pointed to by string 



vajist ap); 


General Utilities( stdlib.h) 

Description 

int 

abs(int j);§ 

Returns the absolute value of j 

void 

abort(void) 

Terminates a program abnormally 

void 

atexit(void (*fun)(void)); 

Registers the function pointed to by fun, to be called without 
arguments at normal program termination 

double 

atof(char *nptr); 

Converts a string to a floating-point value 

int 

atoi(char *nptr); 

Converts a string to an integer value 

long 

atol(char *nptr); 

Converts a string to a long integer value 

void 

*bmalloc(sizeJ _size); 

Allocate memory on a boundary 

void 

*bmalloc8(sizeJ _size); 

- 8-bit version (TMS320C32 only) 

void 

*bmalloc16(sizeJ _size); 

- 16-bit version (TMS32C32 only) 

void 

*bsearch(void ‘key, void ‘base, 

Searches through an array of n objects for the object that key 


sizej n, sizej size, 
int (‘compar) (void)); 

points to 

void 

‘calloc (sizej n, sizej size); 

Allocates and clears memory for n objects, each of size bytes; 

void 

*calloc8(sizeJ _num, 
sizej _size); 

- 8-bit version (TMS320C32 only) 

void 

*calloc16(sizeJ_num, 
sizej _size); 

- 16-bit version (TMS320C32 only) 

divj 

div(int numer, int denom); 

Divides numer by denom producing a quotient and a remainder 

t 

Expands inline if -x is used 


* 

Macro 


§ 

Expands inline unless -xO is used 
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General Utilities (continued) 

Description 


void 

exit(int status); 

Terminates a program normally 

void 

free(void *ptr); 

Deallocates memory space allocated by malloc, calloc, or 
realloc 

void 

free8(void *_prt); 

- 8-bit version (TMS320C32 only) 

void 

free16(void *_prt); 

- 16-bit version (TMS320C32 only) 

long 

labs(long j);§ 

Returns the absolute value of j 

Idivt 

ldiv(long numer, long denom); 

Divides numer by denom producing a quotient and a remainder 

int 

ltoa(long n, char ‘buffer); 

Converts n to the equivalent digit string 

void 

*malloc(size_t size); 

Allocates memory for an object of size bytes 

void 

*malloc8(size_t _size); 

- 8-bit version (TMS320C32 only) 

void 

*malloc16(size_t_size); 

- 16-bit version (TMS320C32 only) 

void 

minit(void); 

Resets all the memory previously allocated by malloc, calloc, 
or realloc 

void 

minit8(void); 

- 8-bit version (TMS320C32 only) 

void 

minit16(void); 

- 16-bit version (TMS320C32 only) 

void 

qsort(void ‘base, size_t n, 

Sorts an array of n members; base points to the first member 


size_t_size, int (*_compar) (void)); 

of the unsorted array, and size specifies the size of members 

int 

rand(void); 

Returns a sequence of pseudorandom integers in the range 0 



to RAN DM AX 

void 

*realloc(void *ptr, size_t size); 

Changes the size of memory pointed to by ptr to size bytes 

void 

*realloc8(void *_ptr, size_t_size); 

- 8-bit version (TMS320C32 only) 

void 

*realloc16(void *_ptr, size_t_size); 

-16-bit version (TMS320C32 only) 

void 

srand(unsigned seed); 

Resets the random number generator 

double 

strtod(char *nptr, char “endptr); 

Converts a string to a floating-point value 

long 

strtol(char *nptr, char “endptr, int 

Converts a string to a long integer value 

base); 



unsigned long strtoul(char *nptr, char **endptr, 
int base); 

Converts a string to an unsigned long integer value 

int 

ti_sprintf(char *s, 

const char ‘format); 

Supports conversion functions required by timeQ 

t 

Expands inline if -x is used 


t 

Macro 


§ 

Expands inline unless -xO is used 
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String Functions( string.h) 

Description 


void 

*memchr(void *s, int c, size_t n);t 

Finds the first occurrence of c in the first n characters of s 

int 

memcmp(void *s1,void *s2, 
size_t n);t 

Compares the first n characters of si to s2 

void 

*memcpy(void *s1, void *s2, 
size_t n);t 

Copies n characters from si to s2 

void 

*memmove(void *s1, void *s2, 
size_t n); 

Moves n characters from si to s2 

void 

*memset(void *s, int c, size_t n);t 

Copies the value of c into the first n characters of s 

char 

*strcat(char *s1, char *s2);t 

Appends s2 to the end of si 

char 

*strchr(char *s, int c);t 

Finds the first occurrence of character c in s 

int 

strcmp(char *s1, char *s2);t 

Compares strings and returns one of the following values: <0 
if si is less than s2; =0 if si is equal to s2; >0 if si is > s2 

int 

*strcoll(char *s1, char *s2); 

Compares strings and returns one of the following values, de¬ 
pending on the locale: <0 if si is less than s2; =0 if si is equal 
to s2; >0 if si is greater than s2 

char 

*strcpy(char *s1, char *s2);t 

Copies string s2 into si 

size_t 

strcspn(char *s1, char *s2); 

Returns the length of the initial segment of si that is made up 
entirely of characters that are not in s2 

char 

*strerror(int errnum); 

Maps the error number in errnum to an error message string 

size_t 

strlen(char *s);t 

Returns the length of a string 

char 

*strncat(char *s1, char *s2, 
size_t n); 

Appends up to n characters from si to s2 

int 

strncmp(char *s1, char *s2, 
size_t n); 

Compares up to n characters in two strings 

char 

*strncpy(char *s1, char *s2, 
size_t n); 

Copies up to n characters of a s2 to si 

char 

*strrchr(char *s, char c);t 

Finds the last occurrence of character c in s 

char 

*strpbrk(char *s1, char *s2); 

Locates the first occurrence in si of any character from s2 

size_t 

strspn(char *s1, char *s2); 

Returns the length of the initial segment of si, which is entirely 
made up of characters from s2 

char 

*strstr(char *s1, char *s2); 

Finds the first occurrence of s2 in si 

char 

*strtok(char *s1, char *s2); 

Breaks si into a series of tokens, each delimited by a character 
from s2 

t 

Expands inline if -x is used 


t 

Macro 


§ 

Expands inline unless -xO is used 
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Nonlocal Jumps (setjmp.h) 

Description 


int 

setjmp(jmp_buf env)^ 

Saves calling environment for later use by longjmp function 

void 

longjmp(jmp_buf env, 

Uses jmp buf argument to restore a previously saved 


int retumval); 

environment 

char 

*asctime(struct tm *timeptr); 

Converts a time to a string 

Time Functions (time.h) 

Description 

clock_t 

clock(void); 

Determines the processor time used 

char 

*ctime(struct time *timeptr); 

Converts time to a string 

double 

timeO); 

difftime(time_t timel, time_t 

Returns the difference between two calendar times 

struct tm *gmtime(time_t *timer); 

Converts local time to Greenwich Mean Time 

struct tm *localtime(time__t *timer); 

Converts time_t value to broken down time 

time_t 

mktime(struct tm *timeptr); 

Converts broken down time to a time_t value 

size_t 

strftime(char *s,‘format, size_t 
maxsize, struct tm ‘timeptr); 

Formats a time into a character string 

time t 

time(time t ‘timer); 

Returns the current calendar time 

t 

Expands inline if -x is used 


t 

Macro 


§ 

Expands inline unless -xO is used 
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5.4 Functions Reference 


This section contains an alphabetical list of the functions and macros declared 
in the header files. The following table lists the functions and macros and 
directs you to the detailed description of the function or macro: 


Function 

or Macro Page 


abort . 

5-22 

abs. 

5-22 

acos. 

5-22 

add_device ... 

5-23 

asctime . 

5-25 

asin . 

5-25 

assert. 

5-26 

atan . 

5-27 

atan2 . 

5-27 

atexit . 

5-27 

atof/atoi/atol .. 

5-28 

bsearch. 

5-30 

calloc. 

5-31 

ceil . 

5-32 

clearerr . 

5-32 

clock . 

5-33 

cos. 

5-33 

cosh. 

5-34 

ctime . 

5-34 

difftime. 

5-34 

div . 

5-35 

exit. 

5-36 

exp. 

5-36 

tabs . 

5-36 

fclose. 

5-37 

feof. 

5-37 

terror . 

5-37 

fflush . 

5-37 

fgetc. 

5-38 

fgetpos. 

5-38 

fgets. 

5-38 


Function 

or Macro Page 


floor . 

5-39 

fmod. 

5-39 

fopen . 

5-39 

fprintf. 

5-40 

fputc. 

5-40 

fputs. 

5-40 

fread . 

5-40 

free. 

5-41 

freopen . 

5-41 

frexp. 

5-42 

fscanf. 

5-42 

fseek . 

5-42 

fsetpos. 

5-43 

ftell. 

5-43 

fwrite . 

5-43 

getc . 

5-43 

getchar . 

5-44 

getenv . 

5-44 

gets . 

5-44 

gmtime. 

5-44 

isxxx. 

5-45 

labs . 

5-22 

Idexp . 

5-46 

Idiv. 

5-35 

localtime . 

5-46 

log . 

5-46 

loglO . 

5-47 

lonjmp . 

5-60 

itoa. 

5-47 

malloc . 

5-48 

memchr. 

5-49 


Function 


or Macro Page 

memcmp . 

5-49 

memcpy. 

5-49 

memmove .... 

5-50 

memset. 

5-50 

minit. 

5-51 

mktime. 

5-52 

modf. 

5-53 

perror. 

5-53 

pow . 

5-54 

printf. 

5-54 

putc . 

5-54 

putchar . 

5-55 

puts . 

5-55 

printf. 

5-54 

qsort. 

5-56 

rand . 

5-57 

realloc . 

5-57 

remove . 

5-58 

rename . 

5-58 

rewind . 

5-59 

scant . 

5-59 

setbuf. 

5-59 

setjmp . 

5-60 

setvbuf. 

5-61 

sin . 

5-61 

sinh . 

5-62 

sprintf. 

5-62 

sqrt. 

5-62 

srand . 

5-57 

sscanf . 

5-63 

strcat . 

5-63 


Function 


or Macro Page 


strchr. 

5-64 

strcmp/strcoll . 

5-64 

strcpy. 

5-65 

strcspn. 

5-65 

strerror. 

5-66 

strftime. 

5-66 

strlen . 

5-67 

strncat. 

5-68 

strncmp. 

5-69 

strncpy. 

5-70 

strpbrk. 

5-71 

strrchr . 

5-64 

strspn. 

5-72 

strstr . 

5-72 

strtod . 

5-73 

strtok . 

5-74 

strtol/strtoul ... 

5-73 

strxfrm. 

5-74 

tan . 

5-75 

tanh . 

5-75 

time . 

5-76 

tmpfile . 

5-76 

tmpnam. 

5-76 

toascii . 

5-76 

tolower/toupper 

5-77 

ungetc. 

5-77 


va_arg/va_end/ 


va_start .... 

5-78 

vfprintf. 

5-79 

vprintf. 

5-79 

vsprintf. 

5-79 
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abort 

Abort 

Syntax 

#include <stdlib.h> 


void abort(void); 

Defined in 

exit.c in rts.src 

Description 

The abort function usually terminates a program with an error code. The 
TMS320C3x/C4x implementation of the abort function calls the exit function 
with a value of 0, and is defined as follows: 

void abort () 

{ 

exit(0) ; 

} 

This makes the abort function equivalent to the exit function. 

abs/labs 

Absolute Value 

Syntax 

#include <stdlib.h> 


int abs(int j); 

long int labs(long int k); 

Defined in 

abs.c in rts.src 

Description 

The C compiler supports two functions that return the absolute value of an 
integer: 

□ The abs function returns the absolute value of an integer j. 

□ The labs function returns the absolute value of a long integer k. 


Since int and long int are functionally equivalent types in TMS320C3x/C4x C, 
the abs and labs functions are also functionally equivalent. The abs and labs 
functions are expanded inline unless the -xO option is used. 

Example 

int x = -5; 

int y = abs (x) ; /* abs returns 5 */ 

acos 

Arc Cosine 

Syntax 

#include <math.h> 


double acos(double x); 

Defined in 

acos.c in rts.src 

Description 

The acos function returns the arc cosine of a floating-point argument x. x must 
be in the range [-1,1]. The return value is an angle in the range [0,71] radians. 

Example 

double realval, radians; 


realval = 0.0; 

radians = acos(realval) ; /* acos return 7C/2 */ 
return (radians); 
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I:?. f. B. WJ Add Device to Device Table 


Syntax 


Defined in 
Description 


Parameters 


Return Value 


#include <stdio.h> 

int add_device(char ‘name, 

unsigned flags, 
int (*dopen)(), 
int (*dclose)(), 
int (*dread)(), 
int (*dwrite)(), 
int (*dlseek)(), 
int (*dunlink)(), 
int (*drename)()); 

lowlev.c in rts.src 

Adds a device record to the device table, allowing that device to be used for 
input/output from C. The first entry in the device table is predefined to be the 
host device on which the debugger is running. The function, add_device(), 
finds the first empty position in the device table and initializes the fields of the 
structure that represent a device. 

To open a stream on a newly-added device, use fopen() with a string of the for¬ 
mat devicename-.fiiename as the first argument. 


name Character string denoting the device name 

flags Device characteristics. The flags denote the following: 

_SSA The device supports only one open stream at 
a time 

_MSA The device supports multiple open streams 


More flags can be added by defining them in stdio.h. 

dopen, dclose, Function pointers to the device drivers are called by the 

dread, dwrite, low-level functions to perform I/O on the specified device, 

dlseek, dunlink, You must declare these functions with the interface 
drename specified in subsection B.2, Overview of Low-Level I/O 

Implementation, on page B-3. The device drivers for the 
host that the ’C3x/’C4x debugger is run on are included in 
the C I/O library. 


0 if successful 
-1 if it fails 
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Example This example does the following: 

□ Adds the device mydevice to the device table 

□ Opens a file named test on that device and associate it with the file *fid 

□ Writes the string Hello, world into the file 

□ Closes the file 


#include <stdio.h> 


/****************************************************************************/ 
/* Declarations of the user-defined device drivers */ 

/****************************************************************************/ 


extern 

extern 

extern 

extern 

extern 

extern 

extern 


int my_open(char *path, unsigned flags, int fno); 
int my_close(int fno); 

int my_read(int fno, char *buffer, unsigned count); 
int my_write(int fno, char *buffer, unsigned count); 
int my_lseek(int fno, long offset, int origin); 
int my_unlink(char *path); 

int my_rename(char *old_name, char *new_name); 


main () 

f 


FILE *f id; 

add_device("mydevice", _MSA, my_open, my_close, my_read, my_write, my_lseek, 

my_unlink, my_rename); 

fid = fopen("mydevice:test","w"); 

fprintf(fid,"Hello, world\n") ; 

fclose(fid); 

} 
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asctime 

Internal Time to String 

Syntax 

#include <time.h> 


char *asctime(struct tm *timeptr); 

Defined in 

asctime.c in rts.src 

Description 

The asctime function converts a broken-down time into a string with the 
following form: 

Mon Jan 11 11:18:36 1988 \n\0 

The function returns a pointer to the converted string. 


For more information about the functions and types that the time.h header 
declares, refer to subsection 5.2.13, page 5-11. 

asin 

Arc Sine 

Syntax 

#include <math.h> 


double asin(double x); 

Defined in 

asin.c in rts.src 

Description 

The asin function returns the arc sine of a floating-point argument x. x must 
be in the range [-1,1]. The return value is an angle in the range [— 7C/2,7C/2] 
radians. 

Example 

double realval, radians; 


realval = 1.0; 

radians = asin(realval) ; /* asin returns 71/2 */ 
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assert 


Syntax 

Defined in 
Description 


Example 


Insert Diagnostic Information Macro 


#include <assert.h> 
void assert(int expression); 
assert.h as a macro 

The assert macro tests an expression; depending upon the value of the 
expression, assert either aborts execution and issues a message or continues 
execution. This macro is useful for debugging. 

□ If expression is false, the assert macro writes information about the partic¬ 
ular call that failed to the standard output, and then aborts execution. 

□ If expression is true, the assert macro does nothing. 

The header file that declares the assert macro refers to another macro, 
NDEBUG. If you have defined NDEBUG as a macro name when the assert.h 
header is included in the source file, then the assert macro is defined to have 
no effect. 

If NDEBUG is not defined when assert.h is included, the assert macro is de¬ 
fined to test the expression and, if false, write a diagnostic message including 
the source filename, line number, and test of expression. 

The assert macro is defined with the printf function, which is not included in the 
library. To use assert, you must either: 

□ Provide your own version of printf, or 

□ Modify assert to output the message by other means 

In this example, an integer i is divided by another integer j. Since dividing by 
0 is an illegal operation, the example uses the assert macro to testj before the 
division. If j = = 0 when this code runs, a message such as: 

Assertion failed (j), file foo.c, line 123 

is sent to standard output. 

int i, j; 

assert(j); 

q = i/j; 
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atari 


Syntax 

Defined in 
Description 

Example 


atan2 


Syntax 

Defined in 
Description 

Example 


atexit 


Syntax 

Defined in 
Description 


Polar Arc Tangent 

#include <math.h> 
double atan(double x); 
atan.c in rts.src 

The atan function returns the arc tangent of a floating-point argument x. The 
return value is an angle in the range [-71/2,71/2] radians. 

double realval, radians; 
realval = 1.0; 

radians = atan(realval); /* return value = 71/4*/ 

Cartesian Arc Tangent 


#include <math.h> 
double atan2(double y, x); 
atan.c in rts.src 

The atan2 function returns the arc tangent of y/x. The function uses the signs 
of the arguments to determine the quadrant of the return value. Both 
arguments cannot be 0. The return value is an angle in the range [—7C,7C] 
radians. 


atan2 (1.0, 1.0) 
atan2 (1.0, -1.0) 
atan2 (-1.0, 1.0) 
atan2 (-1.0, -1.0) 


/* returns 71/4 */ 

/* returns 371/4 */ 
/* returns ±71/4 */ 
/* returns -371/4 */ 


Exit Without Arguments 


#include <stdlib.h> 

void atexit(void (*fun)(void)); 

exit.c in rts.src 

The atexit function registers the function that is pointed to by fun, to be called 
without arguments at normal program termination. Up to 32 functions can be 
registered. 

When the program exits through a call to the exit function, a call to abort, or 
a return from the main function, the functions that were registered are called, 
without arguments, in reverse order of their registration. 
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atof/atoi/atol 


Syntax 

Defined in 
Description 


Example 


Convert ASCII to Number 


#include <stdlib.h> 

double atof(char *nptr); 
int atoi(char *nptr); 
long int atol(char *nptr); 

atof.c and atoi.c in rts.src 

Three functions convert strings to numeric representations: 

□ The atof function converts a string into a floating-point value. Argument 
nptr points to the string; the string must have the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 

□ The atoi function converts a string into an integer. Argument nptr points 
to the string; the string must have the following format: 

[space] [sign] digits 

□ The atol function converts a string into a long integer. Argument nptr 
points to the string; the string must have the following format: 

[space] [sign] digits 

The space is indicated by one or more of the following characters: a space 
(character), a horizontal or vertical tab, a carriage return, a form feed, or a 
newline. Following the space is an optional sign, and then digits that represent 
the integer portion of the number. The fractional part of the number follows, 
then the exponent, including an optional sign. 

The first character that cannot be part of the number terminates the string. 

Since int and long are functionally equivalent in TMS320C3x/C4x C, the atoi 
and atoi functions are also functionally equivalent. 

The functions do not handle any overflow resulting from the conversion. 

int i; 
double d; 

i = atoi ("-3291"); /* i = -3291 */ 
d = atof ("1.23e-2); /* d = .0123 */ 
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bmalloc 


Syntax 

Defined in 
Description 


Allocate Memory on a Boundary 


#include <stdlib.h> 

void *bmalloc(size_t_size); 
void *bmalloc8(size_t_size); 
void *bmalloc16(size_t_size); 

memory.c in rts.src 

The bmalloc function allocates space for an object of size bytes and returns 
a pointer to the space. The packet of the given size is aligned on a boundary 
suitable for TMS320C3x and TMS320C4x circular buffers and bit-reversed 
address buffers. See the TMS320C3x User’s Guide for information on circular 
buffers and bit-reversed addressing. 

The memory that bmalloc uses is in a special memory pool or heap, defined 
in an uninitialized named section called .sysmem in memory.c. The linker sets 
the size of this section from the value specified by the -heap option. Default 
heap size is 1K words. 

For the TMS320C32 processor, 8-bit and 16-bit versions of the bmalloc 
function are provided. The functions bmalloc8 and bmalloc16 are analogous 
to bmalloc; however, memory is allocated from the uninitialized sections 
.sysm8 and .sysm16, respectively. The linker creates a .sysm8 or ,sysm16 
section when a size is specified using the -heap8 or -heap16 option. It will 
create a section of the default size (IK of 8-bit or 16-bit words) when the 
bmalloc8 and bmalloc16 functions are used and the -heap8 and -heap16 
options are not. 

For more information, refer to subsection 4.1.3, Dynamic Memory Allocation, 
on page 4-4. 
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bsearch 


Syntax 

Defined in 
Description 


Example 


Array Search 


#include <stdlib.h> 

void *bsearch(void *key, void *base, size_t nmemb, 
size_t size, int (*compar)(void)); 

bsearch.c in rts.src 

The bsearch function searches through an array of nmemb objects for a 
member that matches the object that key points to. Argument base points to 
the first member in the array; size specifies the size (in bytes) of each member. 

The contents of the array must be in ascending, sorted order. If a match is 
found, the function returns a pointer to the matching member of the array; if 
no match is found, the function returns a null pointer (0). 

Argument compar points to a user-defined function that compares key to the 
array elements. The comparison function should be declared as: 

int cmp(const void *ptrl, const void *ptr2); 

The cmp function compares the objects that ptrl and ptr2 point to and returns 
one of the following values: 

< 0 if *ptr1 is less than *ptr2. 

0 if *ptr1 is equal to *ptr2. 

> 0 if *ptr1 is greater than *ptr2. 


In order for the search to work properly, the comparison must return <0, 0, >0. 

#include <stdlib.h> 

#include <stdio.h> 

int list [] = {1, 3, 4, 6, 8, 9}; 
int diff (const void *, const void *0; 

main ( ) 

{ 

int key = 8; 

int p = bsearch (&key, list, 6, 1, idiff); 

/* p points to list [4] */ 

} 

int idiff (const void *il, const void *i2) 

{ 

return * (int *) il - * (int *) i2; 

} 
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calloc 


Syntax 

Defined in 
Description 


Example 


Allocate and Clear Memory 


#include <stdlib.h> 

void *calloc(size_t nmemb, size_t size); 
void *calloc8(size_t_num, size_t_size); 
void *calloc16(size_t_num, size_t_size); 

memory.c in rts.src 

The calloc function allocates size bytes for each of nmemb objects and re¬ 
turns a pointer to the space. The function initializes the allocated memory to 
all Os. If it cannot allocate the memory (that is, if it runs out of memory), it re¬ 
turns a null pointer (0). 

The memory that calloc uses is in a special memory pool or heap, defined in 
an uninitialized named section called .sysmem in memory.c. The linker sets 
the size of this section from the value specified by the -heap option. Default 
heap size is 1K words. 

For the TMS320C32 processor, 8-bit and 16-bit versions of the calloc function 
are provided. The functions calloc8 and callocl 6 are analogous to calloc; how¬ 
ever, memory is allocated from the uninitialized sections .sysm8 and .sysml 6, 
respectively. The linker creates a .sysm8 or .sysml 6 section when a size is 
specified using the -heap8 or -heap16 option. It will create a section of the 
default size (IK of 8-bit or 16-bit words) when the calloc8 and callocl6 
functions are used and the -heap8 and -heap16 options are not. 

For more information, refer to subsection 4.1.3, Dynamic Memory Allocation, 
on page 4-4. 

This example uses the calloc routine to allocate and clear 10 bytes. 

ptr = calloc (10,2); /*Allocate and clear 20 bytes */ 
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ceil 


Syntax 

Defined in 
Description 

Example 


clearerr 


Syntax 

Defined in 
Description 


Ceiling 


#include <math.h> 
double ceil(double x); 
ceil.c in rts.src 

The ceil function returns a floating-point number that represents the smallest 
integer greater than or equal to x. The ceil function is inlined if the -x2 option 
is used. 

double answer; 

answer = ceil (3.1415) ; /* answer = 4.0 */ 

answer = ceil (-3.5); /* answer = -3.0 */ 


Clear EOF and Error Indicators 

#include <stdio.h> 

void clearerr(FILE *p); 
clearerr.c in rts.src 

Clears the EOF and error indicators for the stream that p points to. 
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clock 


Syntax 

Defined in 
Description 


cos 


Syntax 

Defined in 
Description 

Example 


Processor Time 


#include <time.h> 
clock_t clock(void); 
clock.c in rts.src 

The clock function determines the amount of processor time used. It returns 
an approximation of the processor time used by a program since the program 
began running. The return value can be converted to seconds by dividing by 
the value of the macro CLOCKS_PER_SEC. 

If the processor time is not available or cannot be represented, the clock func¬ 
tion returns the value of -1. 

I-1 

Note: Writing Your Own Clock Function 

The clock function is target-system specific, so you must write your own 
clock function. You must also define the CLOCKS_PER_SEC macro accord¬ 
ing to the granularity of your clock so thatthe value returned by clock() (num¬ 
ber of clock ticks) can be divided by CLOCKS_PER_SEC to produce a value 
in seconds. 

I_I 

For more information about the functions and types that the time.h header de¬ 
clares, refer to subsection 5.2.13, page 5-11. 


Cosine 

#include <math.h> 
double cos(double x); 
cos.c in rts.src 

The cos function returns the cosine of a floating-point number x. The angle x 
is expressed in radians. An argument with a large magnitude may produce a 
result with little or no significance. 

double radians, cval; /* cos returns cval */ 
radians = 3.1415927; 

cval = cos(radians) ; /* return value = -1.0 */ 
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cosh 


Syntax 

Defined in 
Description 

Example 


ctime 


Syntax 

Defined in 
Description 


difftime 


Syntax 

Defined in 
Description 
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Hyperbolic Cosine 

#include <math.h> 
double cosh(double x); 
cosh.c in rts.src 

The cosh function returns the hyperbolic cosine of a floating-point number x. 
A range error occurs if the magnitude of the argument is too large. 

double x, y; 
x = 0.0; 

y = cosh(x); /* return value = 1.0 */ 


Calendar Time 

#include ctime.h> 
char *ctime(time_t *timer); 
ctime.c in rts.src 

The ctime function converts the calendar time (pointed to by timer and repre¬ 
sented as a value of type time_t) to a string. This is equivalent to: 

asctime(localtime(timer)) 

The function returns the pointer returned by the asctime function. 

For more information about the functions and types that the time.h header 
declares, refer to subsection 5.2.13, page 5-11. 


Time Difference 


#include ctime.h> 

double difftime(time_t timel, time_t timeO); 
difftime.c in rts.src 

The difftime function calculates the difference between two calendar times, 
timel minus timeO. The return value is expressed in seconds. 

For more information about the functions and types that the time.h header 
declares, refer to subsection 5.2.13, page 5-11. 
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div/ldiv 


Syntax 

Defined in 
Description 


Example 


Division 


#include <stdlib.h> 

div_t div(int numer, long denom); 
ldiv_t ldiv(long numer, long denom); 

div.c in rts.src 

Two functions support integer division by returning numer divided by denom. 
You can use these functions to get both the quotient and the remainder in a 
single operation. 

□ The div function performs integer division. The input arguments are inte¬ 
gers; the function returns the quotient and the remainder in a structure of 
type div t. The structure is defined as follows: 

typedef struct 
{ 

int quot; /* quotient */ 

int rem; /* remainder */ 

} div_t; 

□ The Idiv function performs long integer division. The input arguments are 
long integers; the function returns the quotient and the remainder in a 
structure of type Idiv t. The structure is defined as follows: 

typedef struct 
{ 

long int quot; /* quotient */ 

long int rem; /* remainder */ 

} ldiv_t; 

If the division produces a remainder, the sign of the quotient is the same as the 
algebraic quotient, and the magnitude of the resulting quotient is the largest 
integer less than the magnitude of the algebraic quotient. The sign of the re¬ 
mainder is the same as the sign of numer. 

Because ints and longs are equivalent types in TMS320C3x/C4x C, these 
functions are also equivalent. 

int i = -10 
int j =3; 

div_t result = div (i, j) ; /* result.quot == -3 */ 

/* result.rem == -1 */ 
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exit 

Normal Termination 

Syntax 

#include <stdlib.h> 


void exit(int status); 

Defined in 

exit.c in rts.src 

Description 

The exit function terminates a program normally. All functions registered by 
the atexit function are called in reverse order of their registration. 


You can modify the exit function to perform application-specific shutdown 
tasks. The unmodified function simply runs in an infinite loop until the system 
is reset. 


Note that the exit function cannot return to its caller. 

exp 

Exponential 

Syntax 

#include <math.h> 


double exp(double x); 

Defined in 

exp.c in rts.src 

Description 

The exp function returns the exponential function of x. The return value is the 
number e raised to the power x. A range error occurs if the magnitude of x is 
too large. 

Example 

double x, y; 


x = 2.0; 

y = exp(x) ; /* y = 7.38905, which is e**2 */ 

fabs 

Absolute Value 

Syntax 

#include <math.h> 


double fabs(double x); 

Defined in 

fabs.c in rts.src 

Description 

The fabs function returns the absolute value of a floating-point number x. The 
fabs function is expanded inline unless the -xO option is used. 

Example 

double x, y; 


x = -57.5; 

y = fabs(x) ; /* return value = +57.5 */ 
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| fclose 

Close File 

Syntax 

#include <stdio.h> 

int fclose(FILE *iop); 

Defined in 

fclose.c in rts.src 

Description 

Flushes the stream that iop points to. When the stream is flushed, the function 
closes the file associated with the stream. 


Test EOF Indicator 

Syntax 

#include <stdio.h> 

int feof(FILE *p); 

Defined in 

feof.c in rts.src 

Description 

Tests the EOF indicator for a stream. The stream is pointed to by p. 


Test Error Indicator 

Syntax 

#include <stdio.h> 

int ferror(FILE *p); 

Defined in 

ferror.c in rts.src 

Description 

Tests the error indicator for a stream. The stream is pointed to by p. 


Flush I/O Buffer 

Syntax 

#include <stdio.h> 

int fflush(register FILE *iop); 

Defined in 

fflush.c in rts.src 

Description 

Flushes the I/O buffer for a stream. The stream is pointed to by iop. 


Runtime-Support Functions 


5-37 
















fgetc, fgetpos, fgets Alphabetical Summary of Runtime-Support Functions 


fgetc 


Syntax 

Defined in 
Description 


fgetpos 


Syntax 

Defined in 
Description 


fgets 


Syntax 

Defined in 
Description 


Read Next Character 

#include <stdio.h> 
int fgetc(register FILE *fp); 
fgetc.c in rts.src 

Reads the next character in a stream, the stream is pointed to by fp. 

Store Object 

#include <stdio.h> 

int fgetpos(FILE *iop, fpos_t *pos); 

fgetpos.c in rts.src 

Stores the object pointed to by pos. The object is stored to the current value 
of the file position indicator for the stream pointed to by iop. 

Read Next Characters 

#include <stdio.h> 

char *fgets(char *ptr, register int size, register FILE *iop); 
fgets.c in rts.src 

Reads the specified number of characters from the stream pointed to by iop. 
The characters are placed in the array named by ptr. The number of characters 
read is size -1. 


5-38 













Alphabetical Summary of Runtime-Support Functions floor, f mod, f open 


floor 


Syntax 

Defined in 
Description 

Example 


fmod 


Syntax 

Defined in 
Description 

Example 


fopen 


Syntax 

Defined in 
Description 


Floor 


#include <math.h> 
double floor(double x); 
floor.c in rts.src 

The floor function returns a floating-point number that represents the largest 
integer less than or equal to x. The floor function is expanded inline if the -x 
option is used. 

double answer; 

answer = floor(3.1415) ; /* answer = 3.0 */ 

answer = floor(-3.5); /* answer = -4.0 */ 

Floating-Point Remainder 


#include <math.h> 

double fmod(double x, double y); 

fmod.c in rts.src 

The fmod function returns the remainder after dividing x by y an integral num¬ 
ber of times. If y==0, the function returns 0. 

double x, y, r; 

x = 11.0; 

Y = 5.0; 

r = fmod(x, y) ; /* fmod returns 1.0 */ 


Open File 
#include <stdio.h> 

FILE *fopen(const char *file, const char *mode); 
fopen.c in rts.src 

Opens the file that file points to. How to open the file is described by a string 
pointed to by mode. 
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fprintf 


Syntax 

Defined in 
Description 


fputc 


Syntax 

Defined in 
Description 


fputs 


Syntax 

Defined in 
Description 


fread 


Syntax 

Defined in 
Description 


Write Stream 

#include <stdio.h> 

int fprintf(FILE *iop, const char *format, ...); 
fprintf.c in rts.src 

Writes to the stream pointed to by iop. How to write the stream is described by 
a string pointed to by format. 

Write Character 

#include <stdio.h> 

int fputc(int c, register FILE *fp); 

fputc.c in rts.src 

Writes a character to a stream. The stream is pointed to by fp. 

Write String 

#include <stdio.h> 

int fputs(const char *ptr, register FILE *iop); 
fputs.c in rts.src 

Writes the string pointed to by ptr to a stream. The stream is pointed to by iop. 

Read Stream 

#include <stdio.h> 

size_t fread(void *ptr, size_t size, size_t count, FILE *iop); 
fread.c in rts.src 

Reads from the stream pointed to by iop. Stores the input in the array pointed 
to by ptr. The number of objects read is count. The size of the objects is size. 
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free 

Deallocate Memory 

Syntax 

#include <stdlib.h> 


void free(void *ptr); 
void free8(void *_ptr); 
void free16(void *_ptr); 

Defined in 

memory.c in rts.src 

Description 

The free function deallocates memory space (pointed to by ptr) that was pre¬ 
viously allocated by a malloc, calloc, or realloc call. This makes the memory 
space available again. If you attempt to free unallocated space, the function 
takes no action and returns. 


For the TMS320C32 processor, 8-bit and 16-bit versions of the free function 
are provided. The functions free8 and free16 are analogous to the 32-bit 
version. 


For more information, refer to subsection 4.1.3, Dynamic Memory Allocation, 
on page 4-4. 

Example 

This example allocates 10 bytes and then frees them. 


char *x; 

x = malloc(10); /* allocate 10 bytes */ 

free(x) ; /* free 10 bytes */ 

freopen 

Open File 

Syntax 

#include <stdio.h> 


FILE *freopen(const char ‘file, const char ‘mode, register FILE *iop); 

Defined in 

fopen.c in rts.src 

Description 

Opens the file pointed to by file, and associates with it the stream pointed to 
by iop. How to open the file is described by a string pointed to by mode. 
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| frexp 

Fraction and Exponent 

Syntax 

#include <math.h> 

double frexp(double value, int *exp); 

Defined in 

frexp30.asm in rts.src 

Description 

The frexp function breaks a floating-point number into a normalized fraction 
and an integer power of 2. The function returns a number x, with a magnitude 
in the range [1/2,1) or 0, so that value == xx2 ex P. The frexp function stores the 
power in the int pointed to by exp. If value is 0, both parts of the result are 0. 

Example 

double fraction; 

int exp; 

fraction = frexp(3.0, &exp); 

/* after execution, fraction is .75 and exp is 2 */ 


Read Stream 

Syntax 

#include <stdio.h> 

int fscanf(FILE *iop, const char *format, ...); 

Defined in 

fscanf.c in rts.src 

Description 

Reads from the stream pointed to by iop. How to read the stream is described 
by a string pointed to by format. 


Set File Position Indicator 

Syntax 

#include <stdio.h> 

int fseek(register FILE *iop, long offset, int ptr); 

Defined in 

fseek.c in rts.src 

Description 

Sets the file position indicator for the stream pointed to by iop. The position is 
specified by ptr. For a binary file, use offset to position the indicator from ptr. 
For a text file, offset must be 0. 
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fsetpos 


Syntax 

Defined in 
Description 


ftell 


Syntax 

Defined in 
Description 


fwrite 


Syntax 

Defined in 
Description 


getc 


Syntax 


Set File Position Indicator 

#include <stdio.h> 

int fsetpos(FILE *iop, const fpos_t *pos); 
fsetpos.c in rts.src 

Sets the file position indicator for the stream pointed to by iop to pos. The 
pointer pos must be a value from fgetpos() on the same stream. 

Get Current File Position Indicator 

#include <stdio.h> 

long ftell(FILE *iop); 
ftell.c in rts.src 

Gets the current value of the file position indicator for a stream. The stream is 
pointed to by iop. 

Write Block of Data 

#include <stdio.h> 

size_t fwrite(const void *ptr, size_t size, size_t count, register FILE *iop); 
fwrite.c in rts.src 

Writes a block of data from the memory pointed to by ptr to a stream. The 
stream is pointed to by iop. 

Read Next Character 

#include <stdio.h> 

int getc(FILE *p); 
fgetc.c in rts.src 

Reads the next character in a file. The file is pointed to by p. 


Defined in 
Description 
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getchar 


Syntax 

Defined in 
Description 


getenv 


Syntax 

Defined in 
Description 


gets 


Syntax 

Defined in 
Description 


gmtime 


Syntax 

Defined in 
Description 
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Read Next Character From Standard Input 

#include <stdio.h> 

int getchar(void); 

fgetc.c in rts.src 

Reads the next character from the standard input device. 

Get Environment Information 

#include <stdlib.h> 

char *getenv(const char *name); 

Iddrv.c in rts.src 

Returns the environment information associated with name. 

Read Next From Standard Input 

#include <stdio.h> 
char *gets(char *ptr); 
fgets.c in rts.src 

Reads an input line from the standard input device. The characters are placed 
in the array named by ptr. 

Greenwich Mean Time 

#include <time.h> 

struct tm *gmtime(time_t *timer); 

gmtime.c in rts.src 

The gmtime function converts a local time pointed to by timer into Greenwich 
Mean Time (represented as a broken-down time). 

The adjustment from local time to GMT is dependent on the local time zone. 
The current time zone is represented by a structure called _tz, of type struct 
tmzone, defined in tmzone.c. Change this structure for the appropriate time 
zone. 

For more information about the functions and types that the time.h header de¬ 
clares, refer to subsection 5.2.13, page 5-11. 
















isxxx 


Syntax 

Defined in 

Description 


Alphabetical Summary of Runtime-Support Functions isXXX 


Character Typing 


#include <ctype.h> 

islower(char c); 
isprint(char c); 
ispunct(char c); 
isspace(char c); 
isupper(char c); 
isxdigit(char c); 

isxxx.c and ctype.c in rts.src 
Also defined in ctype.h as macros 


int isalnum(char c); 

int 

int isalpha(char c); 

int 

int isascii(char c); 

int 

int iscntrl(char c); 

int 

int isdigit(char c); 

int 

int isgraph(char c); 

int 


These functions test a single argument c to see if it is a particular type of char¬ 
acter—alphabetic, alphanumeric, numeric, ASCII, etc. If the test is true (the 
character is the type of character that it was tested to be), the function returns 
a nonzero value; if the test is false, the function returns 0. All of the character¬ 
typing functions are expanded inline if the -x option is used. The character¬ 
typing functions include: 

isalnum identifies alphanumeric ASCII characters (tests for any character 
for which isalpha or isdigit is true). 

isalpha identifies alphabetic ASCII characters (tests for any character for 
which islower or isupper is true). 

isascii identifies ASCII characters (any character from 0-127). 
iscntrl identifies control characters (ASCII characters 0-31 and 127). 
isdigit identifies numeric characters between 0 and 9 (inclusive), 
isgraph identifies any non-space character, 

islower identifies lowercase alphabetic ASCII characters. 

isprint identifies printable ASCII characters, including spaces (ASCII 
characters 32-126). 

ispunct identifies ASCII punctuation characters. 

isspace identifies ASCII spacebar, tab (horizontal or vertical), carriage re¬ 
turn, form feed, and new line characters. 

isupper identifies uppercase ASCII alphabetic characters, 
isxdigit identifies hexadecimal digits (0-9, a-f, A-F). 

The C compiler also supports a set of macros that perform these same 
functions. The macros have the same names as the functions but are prefixed 
with an underscore; for example, Jsascii is the macro equivalent of the isascii 
function. In general, the macros execute more efficiently than the functions. 
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Idexp 


Syntax 

Defined in 
Description 

Example 


localtime 


Syntax 

Defined in 
Description 


log 


Syntax 

Defined in 
Description 

Example 


Multiply by a Power of Two 


#include <math.h> 

double ldexp(double x, int exp); 

Idexp30.asm in rts.src 

The Idexp function multiplies a floating-point number x by a power of 2 given 
by exp and returns x x 2 ex P. The exponent (exp) can be a negative or a positive 
value. A range error may occur if the result is too large. 

double result; 

result = Idexp(1.5, 5); /* result is 48.0 */ 

result = Idexp(6.0, -3); /* result is 0.75 */ 


Local Time 

#include <time.h> 

struct tm *localtime(time_t *timer); 

localtime.c in rts.src 

The localtime function converts a calendar time represented as a value of 
type time_t into a broken-down time in a structure. The function returns a point¬ 
er to the structure representing the converted time. 

For more information about the functions and types that the time.h header 
declares, refer to subsection 5.2.13, page 5-11. 

Natural Logarithm 

#include <math.h> 
double log(double x); 
log.c in rts.src 

The log function returns the natural logarithm of a real number x. A domain 
error occurs if x is negative; a range error occurs if x is 0. 

float x, y; 
x = 2.718282; 

y = log(x); /* Return value = 1.0 */ 


5-46 













Alphabetical Summary of Runtime-Support Functions loglO, Itoa 


loglO 

Common Logarithm 

Syntax 

#include <math.h> 


double Iog10(double x); 

Defined in 

loglO.c in rts.src 

Description 

The loglO function returns the base-10 logarithm (or common logarithm) of a 
real number x. A domain error occurs if x is negative; a range error occurs if 
x is 0. 

Example 

float x, y; 


x = 10.0; 

y = log(x); /* Return value = 1.0 */ 

Itoa 

Convert Long Integer to ASCII 

Syntax 

#include <stdlib.h> 


int ltoa(long n, char *buffer); 

Defined in 

Itoa.c in rts.src 

Description 

The Itoa function converts a long integer n to the equivalent ASCII string and 
writes it into buffer with a null terminator. If the input number n is negative, a 
leading minus sign is output. The Itoa function returns the number of 
characters placed in the buffer, not including the terminator. 

Example 

int i; 


char s [ 10]; 

i = ltoa (-92993L, s) ; /* i = 6, s = "-92993"*/ 
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malloc 


Syntax 

Defined in 
Description 


Example 


Allocate Memory 


#include <stdlib.h> 

void *malloc(size_t size); 
void *malloc8(size_t_size); 
void *malloc16(size_t_size); 

memory.c in rts.src 

The malloc function allocates space for an object of size bytes and returns a 
pointer to the space. If malloc cannot allocate the packet (that is, if it runs out 
of memory), it returns a null pointer (0). This function does not modify the 
memory it allocates. 

The memory that malloc uses is in a special memory pool or heap, defined in 
an uninitialized named section called .sysmem in memory.c. The linker sets 
the size of this section from the value specified by the -heap option. Default 
heap size is 1K words. 

For the TMS320C32 processor, 8-bit and 16-bit versions of the malloc function 
are provided. The functions malloc8 and malloc16 are analogous to malloc; 
however, memory is allocated from the uninitialized sections .sysm8 and 
.sysm16, respectively. The linker creates a .sysm8 or .sysm16 section when 
a size is specified using the -heap8 or -heapl 6 option. It will create a section 
of the default size (1K of 8-bit or 16-bit words) when the malloc8 and mallocl 6 
functions are used and the -heap8 and -heapl 6 options are not. 

For more information, refer to subsection 4.1.3, Dynamic Memory Allocation, 
on page 4-4. 

This example allocates free space for a structure. 

struct xyz *p; 

p = malloc (sizeof (struct xyz)); 
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memchr 

Find First Occurrence of Byte 

Syntax 

#include <string.h> 

void *memchr(void *s, char c, size_t n); 

Defined in 

memchr.c in rts.src 

Description 

The memchr function finds the first occurrence of c in the first n characters of 
the object that s points to. If the character is found, memchr returns a pointer 
to the located character; otherwise, it returns a null pointer (0). 

The memchr function is similar to strchr, except that the object that memchr 
searches can contain values of 0, and c can be 0. The memchr function is 
expanded inline when the -x option is used. 

memcmp 

Memory Compare 

Syntax 

#include <string.h> 

int memcmp(void *s1, void *s2, size_t n); 

Defined in 

memcmp.c in rts.src 

Description 

The memcmp function compares the first n characters of the object that s2 
points to with the object that si points to. The function returns one of the follow¬ 
ing values: 

< 0 if *s1 is less than *s2. 

0 if *s1 is equal to *s2. 

> 0 if *s1 is greater than *s2. 

The memcmp function is similar to strncmp, except that the objects that 
memcmp compares can contain values of 0. The memcmp function is expand¬ 
ed inline when the -x option is used. 

memcpy 

Memory Block Copy — Nonoverlapping 

Syntax 

#include <string.h> 

void *memcpy(void *s1, void *s2, size_t n); 

Defined in 

memcpy.c in rts.src 

Description 

The memcpy function copies n characters from the object that s2 points to into 
the object that si points to. If you attempt to copy characters of overlapping 
objects, the function’s behavior is undefined. The function returns the value of 
si. 

The memcpy function is similar to strncpy, except that the objects that memcpy 
copies can contain values of 0. The memcpy function is expanded inline when 
the -x option is used. 
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| memmove 

Memory Block Copy — Overlapping 

Syntax 

#include <string.h> 

void *memmove(void *s1, void *s2, size_t n); 

Defined in 

memmove.c in rts.src 

Description 

The memmove function moves n characters from the object that s2 points to 
into the object that si points to; the function returns the value of si. The 
memmove function correctly copies characters between overlapping objects. 


Duplicate Value in Memory 

Syntax 

#include <string.h> 

void *memset(void *s, int c, size_t n); 

Defined in 

memset.c in rts.src 

Description 

The memset function copies the value of c into the first n characters of the ob¬ 
ject that s points to. The function returns the value of s. The memset function 
is expanded inline when the -x option is used. 
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minit 


Syntax 

Defined in 
Description 


Reset Dynamic Memory Pool 


#include <stdlib.h> 

void minit(void); 
void minit8(void); 
void minit16(void); 

memory.c in rts.src 

The minit function resets all the space that was previously allocated by calls 
to the malloc, calloc, or realloc functions. 

I-1 

Note: Accessing Objects After Calling the minit Function 

Calling the minit function makes all the memory space in the heap available 
again. Any objects that you allocated previously will be lost; do not try 
to access them. 

I_I 

The memory that minit uses is in a special memory pool or heap, defined in 
an uninitialized named section called .sysmem in memory.c. The linker sets 
the size of this section from the value specified by the -heap option. Default 
heap size is 1K words. 

For the TMS320C32 processor, 8-bit and 16-bit versions of the minit function 
are provided. The functions minit8 and minitl 6 are analogous to the 32-bit 
version; however, memory is allocated from the uninitialized sections .sysm8 
and .sysm16, respectively. The linker creates a .sysm8 or ,sysm16 section 
when a size is specified using the -heap8 or-heap16 option. 

For more information, refer to subsection 4.1.3, Dynamic Memory Allocation, 
on page 4-4. 
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mktime 


Syntax 

Defined in 
Description 


Example 


Convert to Calendar Time 


#include <time.h> 

time_t *mktime(struct tm *timeptr); 

mktime.c in rts.src 


The mktime function converts a broken-down time, expressed as local time, 
into a time value of type time_t. The timeptr argument points to a structure that 
holds the broken-down time. 


The function ignores the original values of tm_wday and tm_yday and does not 
restrict the other values in the structure. After successful completion of time 
conversions, tm_wday and tm_yday are set appropriately, and the other 
components in the structure have values within the restricted ranges. The final 
value of tm_mday is not sent until tm_mon and tm_year are determined. 

The return value is encoded as a value of type time_t. If the calendar time 
cannot be represented, the function returns the value -1. 

This example determines the day of the week that July 4, 2001 falls on. 

#include <time.h> 

static const char *const wday[] = { 

"Sunday", "Monday", "Tuesday", "Wednesday", 
"Thursday", "Friday", "Saturday" }; 


struct tm time_str; 


time_str.tm_year 
time_st r.tm_mon 
time_str.tm_mday 
time_str.tm_hour 
time_str.tm_min 
time_str.tm_sec 
time_str.tm_isdst 


2001 - 1900; 
7; 

4; 

0 ; 

0 ; 

i; 

i; 


mktime(&time_str) ; /* After calling this function, 

time_str.tm_wday contains the day of 
the week for July 4, 2001 */ 


printf ("result is %s\n", wday[time_str.tm_wday]); 

For more information about the functions and types that the time.h header 
declares, refer to subsection 5.2.13, on page 5-11. 
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modf 


Syntax 

Defined in 
Description 

Example 


perror 


Syntax 

Defined in 
Description 


Signed Integer and Fraction 


#include <math.h> 

double modf(double value, double *iptr); 
modf30.asm in rts.src 

The modf function breaks a value into a signed integer and a signed fraction. 
Each of the two parts has the same sign as the input argument. The function 
returns the fractional part of value and stores the integer part as a double at 
the object pointed to by iptr. 

double value, ipart, fpart; 
value = -3.1415; 

fpart = modf(value, &ipart); 

/* After execution, ipart contains -3.0, */ 

/* and fpart contains -0.1415. */ 


Map Error Number 

#include <stdio.h> 
void perror(const char *s); 
perror.c in rts.src 

Maps the error number in s to a string. The function then prints the error mes¬ 
sage. 
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pow 

Raise to a Power 

Syntax 

#include <math.h> 


double pow(double x, double y); 

Defined in 

pow.c in rts.src 

Description 

The pow function returns x raised to the power y. A domain error occurs if x = 0 
and y <0, or if x is negative and y is not an integer. A range error may occur 
if the result is too large to represent. 

Example 

double x, y, z; 


x = 2.0; 

Y = 3.0; 

z = pow(x, y) ; /* return value = 8.0 */ 

printf 

Write to Standard Output 

Syntax 

#include <stdio.h> 


int printf(const char ‘format, ...); 

Defined in 

printf.c in rts.src 

Description 

Writes to the standard output device. How to write the stream is described by 
a string pointed to by format. 

putc 

Write Character 

Syntax 

#include <stdio.h> 


int putc(int x, FILE *p); 

Defined in 

fputc.c in rts.src 

Description 

Writes a character to a stream. The stream is pointed to by p. 
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putchar 

Write Character to Standard Output 

Syntax 

#include <stdlib.h> 


int putchar(int x); 

Defined in 

fputc.c in rts.src 

Description 

Writes a character to the standard output device. 

puts 

Write to Standard Output 

Syntax 

#include <stdlib.h> 


int puts(const char *ptr); 

Defined in 

fputs.c in rts.src 

Description 

Writes a string to the standard output device. The string is pointed to by ptr. 
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qsort 


Syntax 

Defined in 
Description 


Example 


Array Sort 


#include <stdlib.h> 

void qsort(void *base, size_t n, size_t size, int (*compar) (void)); 
qsort.c in rts.src 

The qsort function sorts an array of n members. Argument base points to the 
first member of the unsorted array; argument size specifies the size of each 
member. 

This function sorts the array in ascending order. 

Argument compar points to a function that compares key to the array 
elements. The comparison function should be declared as: 

int cmp(void *ptrl, void *ptr2); 

The cmp function compares the objects that ptrl and ptr2 point to and returns 
one of the following values: 

< 0 if *ptr1 is less than *ptr2. 

0 if *ptr1 is equal to *ptr2. 

> 0 if *ptr1 is greater than *ptr2. 

The array sort will not work correctly if the CMP function fails to return the cor¬ 
rect values for all three conditions. 

In the following example, a short list of integers is sorted with qsort. 

#include <stdlib.h> 

int list [ ] = {3, 1, 4, 1, 5, 9, 2, 6}; 
int idiff (const void *, const void *); 

main ( ) 

{ 

qsort (list, 8, 1, idiff); 

/* after sorting, list [ ]= = { 1, 1, 2, 3, 4, 5, 6, 9} */ 

} 

int idiff (const void *il, const void *i2) 

{ 

return *(int *)il - *(int *)i2; 

} 
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rand/srand 


Syntax 

Defined in 
Description 


realloc 


Syntax 

Defined in 
Description 


Random Integer 


#include <stdlib.h> 

int rand(void); 

void srand(unsigned int seed); 
rand.c in rts.src 

Two functions work together to provide pseudorandom sequence generation: 

□ The rand function returns pseudorandom integers in the range 
0—RAND_MAX. For the TMS320C3x/C4x C compiler, the value of 
RAND_MAX is 2147483646 (23 1 -2). 

□ The srand function sets the value of the random number generator seed 
so that a subsequent call to the rand function produces a new sequence 
of pseudorandom numbers. The srand function does not return a value. 

If you call rand before calling srand, rand generates the same sequence it 
would produce if you first called srand with a seed value of 1. If you call srand 
with the same seed value, rand generates the same sequence of numbers. 


Change Heap Size 


#include <stdlib.h> 

void *realloc(void *ptr, size_t size); 
void *realloc8(void *_ptr, size_t_size); 
void *realloc16(void *_ptr, size_t_size); 

memory.c in rts.src 

The realloc function changes the size of the allocated memory pointed to by 
ptr, to the size specified in bytes by size. The contents of the memory space 
(up to the lesser of the old and new sizes) is not changed. 

□ If ptr is 0, realloc behaves like malloc. 

□ If ptr points to unallocated space, the function takes no action and returns. 

□ If the space cannot be allocated, the original memory space is not 
changed, and realloc returns 0. 

□ If size = 0 and ptr is not null, realloc frees the space that ptr points to. 
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If, in order to allocate more space, the entire object must be moved, realloc 
returns a pointer to the new space. Any memory freed by this operation is 
deallocated. If an error occurs, the function returns a null pointer (0). 

The memory that realloc uses is in a special memory pool or heap, defined in 
an uninitialized named section called .sysmem in memory.c. The linker sets 
the size of this section from the value specified by the -heap option. Default 
heap size is 1K words. 

For the TMS320C32 processor, 8-bit and 16-bit versions of the realloc function 
are provided. The functions realloc8 and realloc16 are analogous to realloc; 
however, memory is allocated from the uninitialized sections .sysm8 and 
.sysm16, respectively. The linker creates a .sysm8 or .sysm16 section when 
a size is specified using the -heap8 or -heapl 6 option. It will create a section 
of the default size (1K of 8-bit or 16-bit words) when the realloc8 and reallocl 6 
functions are used and the -heap8 and -heapl 6 options are not. 

For more information, refer to subsection 4.1.3, Dynamic Memory Allocation, 
on page 4-4. 


| remove 

Remove File 

Syntax 

#include <stdio.h> 


int remove(const char ‘file); 

Defined in 

remove.c in rts.src 

Description 

Makes the file pointed to no longer available by that name. The file is pointed 
to by file. 


rename 


Rename File 


Syntax 

Defined in 
Description 


#include <stdio.h> 

int rename(const char *old, const char *new); 
lowlev.c in rts.src 

Renames the file pointed to by old. The new name is pointed to by new. 
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rewind 


Syntax 

Defined in 
Description 


scant 


Syntax 

Defined in 
Description 


setbuf 


Syntax 

Defined in 
Description 


Position File Position Indicator to Beginning of File 

#include <stdio.h> 

void rewind(register FILE *iop); 

rewind.c in rts.src 

Sets the file position indicator for a stream to the beginning of the file. The file 
is pointed to by iop. 

Read Stream From Standard Input 

#include <stdio.h> 

int scanf(const char *format, ...); 

fscanf.c in rts.src 

Reads from the stream from the standard input device. How to read the stream 
is described by a string pointed to by format. 

Specify Buffer for Stream 

#include <stdio.h> 

void setbuf(register FILE *iop, char *buf); 
setbuf.c in rts.src 

Specifies the buffer used by the stream pointed to by iop. If buf is set to null, 
buffering is turned off. No value is returned. 
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setjmp/longjmp 


Syntax 

Defined in 
Description 


Example 


Nonlocal Jumps 


#include <setjmp.h> 

int setjmp(jmp_buf env); 

void longjmp(jmp_buf env, int returnval); 

setjmp.asm in rts.src 

The setjmp.h header defines one type, one macro, and one function for 
bypassing the normal function call and return discipline: 

□ The jmp_buf type is an array type suitable for holding the information 
needed to restore a calling environment. 

□ The setjmp macro saves its calling environment in the jmp_buf argument 
for later use by the longjmp function. 

If the return is from a direct invocation, the setjmp macro returns the value 
zero. If the return is from a call to the longjmp function, the setjmp macro 
returns a nonzero value. 

□ The longjmp function restores the environment that was saved in the 
jmp_buf argument by the most recent invocation of the setjmp macro. If 
the setjmp macro was not invoked, or if it terminated execution irregularly, 
the behavior of longjmp is undefined. 

After longjmp is completed, the program execution continues as if the 
corresponding invocation of setjmp had just returned returnval. The 
longjmp function will not cause setjmp to return a value of zero even if 
returnval is zero. If returnval is zero, the setjmp macro returns the value 1. 

These functions are typically used to effect an immediate return from a deeply 
nested function call: 

#include <setjmp.h> 
jmp_buf env; 

main() 

{ 

int encode; 

if ((errcode = setjmp(env)) == 0) 

nestl (); 
else 

switch (errcode) 


nest42 () 

{ 

if (input() == ERRCODE42) 

/* return to setjmp call in main */ 

longjmp (env, ERRCODE42); 
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setvbuf 


Syntax 

Defined in 
Description 


sin 


Syntax 

Defined in 
Description 

Example 


Define and Associate Buffer With Stream 


#include <stdio.h> 

int setvbuf(register FILE *iop, register char *buf, register int type, 
register size t_size); 

setbuf.c in rts.src 

Defines and associates the buffer used by the stream pointed to by iop. If buf 
is set to null, a buffer is allocated. If buf names a buffer, that buffer is used for 
the stream. The t_size parameter specifies the size of the buffer. The type pa¬ 
rameter specifies the type of buffering as follows: 

_IOFBF Full buffering occurs 

_IOLBF Line buffering occurs 

_IONBF No buffering occurs 


Sine 


#include <math.h> 
double sin(double x); 
sin.c in rts.src 

The sin function returns the sine of a floating-point number x. x is an angle ex¬ 
pressed in radians. An argument with a large magnitude may produce a result 
with little or no significance. 

double radian, sval; /* sval is returned by sin */ 
radian = 3.1415927; 

sval = sin(radian) ; /* sin returns -1.0 */ 
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sinh 


Syntax 

Defined in 
Description 

Example 


sprintf 


Syntax 

Defined in 
Description 


sqrt 


Syntax 

Defined in 
Description 

Example 


Hyperbolic Sine 

#include <math.h> 
double sinh(double x); 
sinh.c in rts.src 

The sinh function returns the hyperbolic sine of a floating-point number x. A 
range error occurs if the magnitude of the argument is too large. 

double x, y; 
x = 0.0; 

y = sinh(x); /* return value = 0.0 */ 

Write Stream 

#include <stdio.h> 

int sprintf(char ‘string, const char ‘format, ...); 
sprintf.c in rts.src 

Writes to the array pointed to by string. How to write the stream is described 
by a string pointed to by format. 

Square Root 

#include <math.h> 
double sqrt(double x); 
sqrt30.asm in rts.src 

The sqrt function returns the non-negative square root of a real number x. A 
domain error occurs if the argument is negative. 

double x, y; 
x = 100.0; 

y = sqrt(x) ; /* return value = 10.0 */ 
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sscanf 


Syntax 

Defined in 
Description 


strcat 


Syntax 

Defined in 
Description 

Example 


Read Stream 

#include <stdio.h> 

int sscanf(const char *str, const char ‘format, ...); 
sscanf.c in rts.src 

Reads from the string pointed to by str. How to read the stream is described 
by a string pointed to by format. 


Concatenate Strings 


#include <string.h> 

char *strcat(char *s1, char *s2); 

strcat.c in rts.src 

The strcat function appends a copy of s2 (including the terminating null 
character) to the end of si. The initial character of s2 overwrites the null char¬ 
acter that originally terminated si. The function returns the value of si. The 
strcat function is expanded inline if the -x option is used. 

In the following example, the character strings pointed to by a, b, and c were 
assigned to point to the strings shown in the comments. In the comments, the 
notation “\0” represents the null character: 

char *a, *b, *c; 


/* a —> "The quick black fox\0" */ 

/* b —> " jumps over \0" */ 

/* c —> "the lazy dog.\0" */ 

strcat (a,b); 

/* a —> "The quick black fox jumps over \0" */ 


strcat (a,c); 

/* a —> "The quick black fox jumps over the lazy dog.XO"*/ 
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strchr 


Syntax 

Defined in 
Description 

Example 


strcmp/strcoll 


Syntax 

Defined in 
Description 

Example 


Find First Occurrence of a Character 

#include <string.h> 
char *strchr(char *s, char c); 
strchr.c in rts.src 

The strchr function finds the first occurrence of c in s. If strchr finds the charac¬ 
ter, it returns a pointer to the character; otherwise, it returns a null pointer (0). 
The strchr function is expanded inline if the -x option is used. 

char *a = "When zz comes home, the search is on for z's."; 
char *b; 

char the_z = 'z'; 

b = strchr(a,the_z); 

After this example, b points to the first z in zz. 

String Compare 

#include <string.h> 

int strcmp(char *s1, char *s2); 
int strcoll( char *s1, char *s2); 

strcmp.c in rts.src 

The strcmp and strcoll functions compare s2 with si. The functions are 
equivalent; both functions are supported to provide compatibility with ANSI C. 
The strcmp function is expanded inline if the -x option is used. 

The functions return one of the following values: 

< 0 if *s1 is less than *s2. 

0 if *s1 is equal to *s2. 

> 0 if *s1 is greater than *s2. 

char *stra = "why ask why"; 
char *strb = "just do it"; 
char *strc = "why ask why"; 

if (strcmp(stra, strb) > 0) 

{ 

/* statements here will be executed */ 

} 

if (strcoll(stra, strc) == 0) 

{ 

/* statements here will be executed also */ 

} 
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strcpy 


Syntax 

Defined in 
Description 

Example 


strcspn 


Syntax 

Defined in 
Description 

Example 


String Copy 


#include <string.h> 

char *strcpy(char *s1, char *s2); 

strcpy.c in rts.src 

The strcpy function copies s2 (including the terminating null character) into 
si. If you attempt to copy strings that overlap, the function’s behavior is 
undefined. The function returns a pointer to si. The strcpy function is expand¬ 
ed inline if the -x option is used. 

In the following example, the strings pointed to by a and b are two separate 
and distinct memory locations. In the comments, the notation “\0” represents 
the null character: 

char *a = "The quick black fox"; 
char *b = " jumps over 

/* a --> "The quick black fox\0" */ 

/* b —> " jumps over \0" */ 

strcpy(a,b); 

/* a —> " jumps over \0" */ 

/* b —> " jumps over \0" */ 


Find Number of Unmatching Characters 


#include <string.h> 

size_t strcspn(char *s1, char *s2); 

strcspn.c in rts.src 

The strcspn function returns the length of the initial segment of si, which is 
made up entirely of characters that are not in s2. If the first character in si is 
in s2, the function returns 0. 

char *stra = "who is there?"; 

char *strb = "abcdefghijklmnopqrstuvwxyz"; 

char *strc = "abcdefg"; 

size_t length; 

length = strcspn(stra,strb); /* length = 0 */ 

length = strcspn(stra,strc) ; /* length = 9 */ 
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strerror 


Syntax 

Defined in 
Description 


strfti me 


Syntax 

Defined in 
Description 


String Error 

#include <string.h> 
char *strerror(int errnum); 
strerror.c in rts.src 

The strerror function returns the string error. This function is supplied to pro¬ 
vide ANSI compatibility. 


Format Time 


#include <time.h> 

size_t *strftime(char *s, size_t maxsize, char ‘format, 
struct tm *timeptr); 

strftime.c in rts.src 

The strftime function formats a time (pointed to by timeptr) according to a 
format string and returns the formatted result in the string s. Up to maxsize 
characters can be written to s. The format parameter is a string of characters 
that tells the strftime function how to format the time. The following list shows 
the valid characters and describes what each character expands to. 

Character is replaced by... 

%a the abbreviated weekday name (Mon, Tue, . . .) 

%a the full weekday name. 

%b the abbreviated month name (Jan, Feb, . . . ) 

%b the locale’s full month name 

%c the date and time representation 

%d the day of the month as a decimal number (0-31) 

%H the hour (24-hour clock) as a decimal number (00-23) 

%i the hour (12-hour clock) as a decimal number (01 -12) 

% j the day of the year as a decimal number (001-366) 

%m the month as a decimal number (01-12) 

%M the minute as a decimal number (00-59) 

%P the locale’s equivalent of either A.M. or P.M. 

%s the second as a decimal number (00-50) 

%u the week number of the year (Sunday is the first day of the week) as a 
decimal number (00-52) 
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strlen 


Syntax 

Defined in 
Description 

Example 


%x the date representation 
%x the time representation 

%y the year without century as a decimal number (00-99) 

%y the year with century as a decimal number 

%z the time zone name, or by no characters if no time zone exists 

For more information about the functions and types that the time.h header de¬ 
clares, refer to subsection 5.2.13, page 5-11. 


Find String Length 


#include <string.h> 
size_t strlen(char *s); 
strlen.c in rts.src 

The strlen function returns the length of s. In C, a character string is terminated 
by the first byte with a value of 0 (a null character). The returned result does 
not include the terminating null character. The strlen function is expanded in¬ 
line if the -x option is used. 


char *stra = "who is there?"; 

char *strb = "abcdefghijklmnopqrstuvwxyz"; 

char *strc = "abcdefg"; 

size_t length; 

length = strlen(stra) ; /* length = 

length = strlen(strb) ; /* length = 

length = strlen(strc) ; /* length = 


13 */ 
26 */ 
7 */ 
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| strncat 

Concatenate Strings 

Syntax 

#include <string.h> 

Defined in 

char *strncat(char *s1, char *s2, size_t n); 
strncat.c in rts.src 

Description 

The strncat function appends up to n characters of s2 (including the terminat¬ 
ing null character) to the end of si. The initial character of s2 overwrites the 
null character that originally terminated si; strncat appends a null character 
to the result. The function returns the value of si. 

Example 

In the following example, the character strings pointed to by a, b, and c were 
assigned the values shown in the comments. In the comments, the notation 
“\0” represents the null character: 

char *a, *b, *c; 

size_t size = 13; 


/* a—> "I do not like them,\0" */; 

/* b —> " Sam I am, \0" */; 

/* c —> "I do not like green eggs and ham\0" */; 

strncat (a,b,size); 

/* a —> "I do not like them, Sam I am, \0" */; 

strncat (a,c,size); 

/* a —> "I do not like them, Sam I am, I do not like\0" */; 
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strncmp 


Syntax 

Defined in 
Description 


Example 


Compare Strings 


#include <string.h> 

int strncmp(char *s1, char *s2, size_t n); 
strncmp.c in rts.src 

The strncmp function compares up to n characters of s2 with si. The function 
returns one of the following values: 

< 0 if *s1 is less than *s2. 

0 if *s1 is equal to *s2. 

> 0 if *s1 is greater than *s2. 

char *stra = "why ask why"; 
char *strb = "just do it"; 
char *strc = "why not?"; 
size_t size = 4; 

if (strcmp(stra, strb, size) > 0) 

{ 

/* statements here will get executed */ 

} 

if (strcmp(stra, strc, size) == 0) 

{ 

/* statements here will get executed also */ 

} 
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strncpy 


Syntax 

Defined in 
Description 


Example 


String Copy 


#include <string.h> 

char *strncpy(char *s1, char *s2, size_t n); 
strncpy.c in rts.src 

The strncpy function copies up to n characters from s2 into si. If s2 is n 
characters long or longer, the null character that terminates s2 is not copied. 
If you attempt to copy characters from overlapping strings, the function’s 
behavior is undefined. If s2 is shorter than n characters, strncpy appends null 
characters to si so that si contains n characters. The function returns the val¬ 
ue of si. 

Note that strb contains a leading space to make it five characters long. Also 
note that the first five characters of strc are an T, a space, the word “am”, and 
another space, so that after the second execution of strncpy, stra begins with 
the phrase “I am” followed by two spaces. In the comments, the notation “\0” 
represents the null character. 

char *stra = "she's the one mother warned you of"; 
char *strb = " he's"; 

char *strc = "I am the one father warned you of"; 
char *strd = "oops"; 
size_t length = 5; 

strncpy (stra,strb,length); 


/* stra—> " he's the one mother warned you of\0" */; 
/* strb—> " he's\0" */; 
/* strc—> "I am the one father warned you of\0" */; 
/* strd—> "oops\0" */; 

strncpy (stra,strc,length); 

/* stra—> "I am the one mother warned you of\0" */; 
/* strb—> " he's\0" */; 
/* strc—> "I am the one father warned you of\0" */; 
/* strd—> "oops\0" */; 

strncpy (stra,strd,length); 

/* stra—> "oops\0" */; 
/* strb—> " he's\0" */; 
/* strc—> "I am the one father warned you of\0" */; 
/* strd—> "oops\0" */; 
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| strpbrk 

Find Any Matching Character 

Syntax 

#include <string.h> 

char *strpbrk(char *s1, char *s2); 

Defined in 

strpbrk.c in rts.src 

Description 

The strpbrk function locates the first occurrence in si of any character in s2. 
If strpbrk finds a matching character, it returns a pointer to that character; 
otherwise, it returns a null pointer (0). 

Example 

char *stra = "it wasn't me"; 

char *strb = "wave"; 

char *a; 

a = strpbrk (stra,strb); 

After this example, a points to the “w” in wasn’t. 


Find Last Occurrence of a Character 

Syntax 

#include <string.h> 

char *strrchr(char *s, int c); 

Defined in 

strrchr.c in rts.src 

Description 

The strrchr function finds the last occurrence of c in s. If strrchr finds the char¬ 
acter, it returns a pointer to the character; otherwise, it returns a null pointer 
(0). The strrchr function is expanded inline if the -x option is used. 

Example 

char *a = "When zz comes home, the search is on for z's"; 

char *b; 

char the_z = 'z'; 

b = strrchr(a, the_Z); 

After this example, b points to the z in zs near the end of the string. 
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strspn 


Syntax 

Defined in 
Description 

Example 


strstr 


Syntax 

Defined in 
Description 

Example 


Find Number of Matching Characters 


#include <string.h> 
size_t *strspn(int *s1, int *s2); 
strspn.c in rts.src 

The strspn function returns the length of the initial segment of si, which is 
entirely made up of characters in s2. If the first character of si is not in s2, the 
strspn function returns 0. 

char *stra = "who is there?"; 

char *strb = "abcdefghijklmnopqrstuvwxyz"; 

char *strc = "abcdefg"; 

size_t length; 

length = strcspn(stra,strb); /* length = 3 */ 

length = strcspn(stra,strc); /* length = 0 */ 


Find Matching String 


#include <string.h> 

char *strstr(char *s1, char *s2); 

strstr.c in rts.src 

The strstr function finds the first occurrence of s2 in si (excluding the 
terminating null character). If strstrfinds the matching string, it returns a pointer 
to the located string; if it doesn’t find the string, it returns a null pointer. If s2 
points to a string with length 0, strstr returns si. 

char *stra = "so what do you want for nothing?"; 
char *strb = "what"; 
char *ptr; 

ptr = strstr(stra,strb); 

The pointer ptr now points to the “w” in “what” in the first string. 
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strtod/strtol/ 

strtoul 


Syntax 


Defined in 
Description 


Convert String to Numeric Value 


#include <stdlib.h> 

double strtod(char *nptr, char **endptr); 
long int strtol(char *nptr, char **endptr, int base); 

unsigned long int strtoul(char *nptr, char **endptr, int base); 

strtod.c in rts.src, strtol.c in rts.src and strtoul.c in rts.src 

Three functions convert ASCII strings to numeric values. For each function, 
argument nptr points to the original string. Argument endptr points to a pointer; 
the functions set this pointer to point to the first character after the converted 
string. The functions that convert to integers also have a third argument, base, 
which tells the function on which base to interpret the string. 

□ The strtod function converts a string to a floating-point value. The string 
must have the following format: 

[space] [sign] digits [.digits] [e[E [sign] integer] 

The function returns the converted string; if the original string is empty or 
does not have the correct format, the function returns a 0. If the converted 
string would cause an overflow, the function returns + HUGE_VAL; if the 
converted string would cause an underflow, the function returns 0. If the 
converted string causes an overflow or an underflow, errno is set to the 
value of ERANGE. 

□ The strtol function converts a string to a long integer. The string must have 
the following format: 

[space] [sign] digits [.digits] [e[E [sign] integer] 

□ The strtoul function converts a string to an unsigned long integer. The 
string must be specified in the following format: 

[space] [sign] digits [.digits] [e[E [sign] integer] 

The space is indicated by one or more of the following characters: space bar, 
horizontal or vertical tab, carriage return, form feed, or newline. Following the 
space is an optional sign, and then digits that represent the integer portion of 
the number. The fractional part of the number follows, then the exponent, in¬ 
cluding an optional sign. 

The first unrecognized character terminates the string. The pointer that endptr 
points to is set to point to this character. 
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strtok 


Syntax 

Defined in 
Description 

Example 


strxfrm 


Syntax 

Defined in 
Description 


Break String into Token 


#include <string.h> 

char *strtok(char *s1, char *s2); 

strtok.c in rts.src 

Successive calls to the strtok function break si into a series of tokens, each 
delimited by a character from s2. Each call returns a pointer to the next token. 
The first call to strtok uses the string si. Successive calls use a null pointer as 
the first argument. The value of s2 can change at each invocation. It is impor¬ 
tant to note that si is altered by the strtok function. 

After the first invocation of strtok in the example below, the pointer stra points 
to the string “excuse” because strtok has inserted a null character where the 
first space used to be. In the comments, the notation “\0" represents the null 
character. 

char *stra = "excuse me while I kiss the sky"; 
char *ptr; 

ptr = strtok (stra," "); /* ptr --> "excuseXO" */ 

ptr = strtok (0," "); /* ptr --> "me\0" */ 

ptr = strtok (0," "); /* ptr --> "while\0" */ 


Convert Characters 

#include <string.h> 

size_t strxfrm(char *tostring, const char *fromstring, size_t n); 
strxfrm.c in rts.src 

Converts the characters of one string into another string. The n number of 
characters pointed to by fromstring are converted into the n characters pointed 
to by tostring. 
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tan 


Syntax 

Defined in 
Description 

Example 


tanh 


Syntax 

Defined in 

Description 

Example 


Tangent 

#include <math.h> 
double tan(double x); 
tan.c in rts.src 

The tan function returns the tangent of a floating-point number x. x is an angle 
expressed in radians. An argument with a large magnitude may produce a re¬ 
sult with little or no significance. 

double x, y; 
x = 3.1415927/4.0; 

y = tan(x); /* return value = 1.0 */ 

Hyperbolic Tangent 

#include <math.h> 

double tanh(double x); 

tanh.c in rts.src 

The tanh function returns the hyperbolic tangent of a floating-point number x. 

double x, y; 
x = 0.0; 

y = tanh(x); /* return value = 0.0 */ 
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time 

Time 

Syntax 

#include <time.h> 


time_t time(time_t *timer); 

Defined in 

time.c in rts.src 

Description 

The time function determines the current calendar time, represented as a val¬ 
ue of type time_t. The value is the number of seconds since 12:00 A.M., Jan 
1, 1900. If the calendar time is not available, the function returns -1. If timer 
is not a null pointer, the function also assigns the return value to the object that 
timer points to. 


For more information about the functions and types that the time.h header de¬ 
clares, refer to subsection 5.2.13, page 5-11. 


1-1 

Note: Writing Your Own Time Function 


The time function is target-system specific, so you must write your own time 
function. 

1_1 

tmpfile 

Create Temporary File 

Syntax 

#include <stdlib.h> 


FILE *tmpfile(void); 

Defined in 

tmpfile.c in rts.src 

Description 

Creates a temporary file. 

tmpnam 

Generate Valid Filename 

Syntax 

#include <stdlib.h> 


char *tmpnam(char *s); 

Defined in 

tmpnam.c in rts.src 

Description 

Generates a string that is a valid filename. 

toascii 

Convert to ASCII 

Syntax 

#include <ctype.h> 

int toascii(char c); 

Defined in 

toascii.c in rts.src 

Description 

The toascii function ensures that c is a valid ASCII character by masking the 
lower seven bits. There is also an equivalent macro, _toascii. 
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tolower/toupper 


Syntax 

Defined in 

Description 

Example 


ungetc 


Syntax 

Defined in 
Description 


Convert Case 


#include <ctype.h> 

int tolower(char c); 
int toupper(char c); 

tolower.c in rts.src 
toupper.c in rts.src 

Two functions convert the case of a single alphabetic character, c, to upper or 
lower case: 

□ The tolower function converts an uppercase argument to lowercase. If c 
is not an uppercase letter, tolower returns it unchanged. 

□ The toupper function converts a lowercase argument to uppercase. If c 
is not a lowercase letter, toupper returns it unchanged. 

The functions have macro equivalents named _tolower and _toupper. 

tolower ('A') /* returns 'a' */ 

tolower ('+') /* returns '+' */ 


Write Character to Stream 

#include <stdio.h> 

int ungetc(int c, FILE *p); 
ungetc.c in rts.src 

Writes the character c to a stream. The stream is pointed to by p. 
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Variable-Argument Macros/Functions 


Syntax 


Defined in 
Description 


Example 


#include <stdarg.h> 

type va_arg(ap, type)-, 

void va_end(ap); 

void va_start(ap, parmN)-, 

vajist *ap; 

stdarg.h as macros 

Some functions can be called with a varying number of arguments that have 
varying types. Such functions, called variable-argument functions, can use the 
following macros to step through argument lists at runtime. The ap parameter 
points to an argument in the variable-argument list. 

□ The va_start macro initializes ap to point to the first argument in an argu¬ 
ment list for the variable-argument function. The parmN parameter points 
to the rightmost parameter in the fixed, declared list. 

□ The va_arg macro returns the value of the next argument in a call to a 
variable-argument function. Each time you call va_arg, it modifies ap so 
that successive arguments for the variable-argument function can be 
returned by successive calls to va_arg (va_arg modifies ap to point to the 
next argument in the list). The type parameter is a type name; it is the type 
of the current argument in the list. 

□ The va_end macro resets the stack environment after va_start and 
va_arg are used. 

Note that you must call va_start to initialize ap before calling va_arg or 
va_end. 

#include<stdarg.h> 

int printf(char *fmt, ...) 

{ 

int i; 
char* s; 

va_list ap; 
va_start(ap, fmt); 

/* ... */ 

i = va_arg(ap, int); /* Get next arg, an integer */ 

s = va_arg(ap, char *); /* Get next arg, a string */ 

i = va_arg(ap, long); /* Get next arg, a long */ 

va_end(ap); 
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} 


/* Reset 


/ 






Alphabetical Summary of Runtime-Support Functions vfprintf, vprintf, VSprintf 


vfprintf 


Syntax 

Defined in 
Description 


vprintf 


Syntax 

Defined in 
Description 


vsprintf 


Syntax 

Defined in 
Description 


Write to Stream 

#include <stdio.h> 

int vfprintf(FILE *iop, const char ‘format, vajist ap); 
vfprintf.c in rts.src 

Writes to the stream pointed to by iop. How to write the stream is described by 
a string pointed to by format. The ap parameter is the argument list. 

Write to Standard Output 

#include <stdio.h> 

int vprintf(const char ‘format, vajist ap); 
vprintf.c in rts.src 

Writes to the standard output device. How to write the stream is described by 
a string pointed to by format. The ap parameter is the argument list. 

Write Stream 

#include <stdio.h> 

int vsprintf(char ‘string, const char ‘format, vajist ap); 
vsprintf.c in rts.src 

Writes to the array pointed to by string. How to write the stream is described 
by a string pointed to by format. The ap parameter is the argument list. 


Runtime-Support Functions 
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Chapter 6 


Library-Build Utility 


When using the TMS320C3x/C4x C compiler, you can compile your code 
under a number of different configurations and options, which are not neces¬ 
sarily compatible with one another. Since it would be cumbersome to include 
all possible combinations in individual runtime-support libraries, this package 
includes the source file, rts.src, that contains all runtime-support functions, 
and all floating-point support functions. By using the mk30 utility described in 
this chapter you can custom build your own runtime-support libraries for the 
options you select. 


These are the topics covered in this chapter: 


Topic 


Page 


6.1 Invoking the Library-Build Utility 

6.2 Options Summary. 


EH 

5-4 
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Invoking the Library-Build Utility 


6.1 Invoking the Library-Build Utility 

The general syntax for invoking the library utility is: 


mk30 [options] src_arch1 [-1 obj.libl] [src_arch2 [-\obj.lib2]] 


mk30 is the command that invokes the utility. 

options can appear anywhere on the command line or in a command file. 
(Options are discussed in Section 6.2 and below.) 

src_arch is the name of a source archive file. For each source archive 
named, mk30 will build an object library according to the runtime 
model specified by the command line options. 

-I obj.lib is the optional object library name. If you do not specify a name 
for the library, mk30 uses the name of the source archive and 
appends a .lib suffix. For each source archive file specified, a cor¬ 
responding object library file is created. An object library cannot 
be built from multiple source archive files. 

The mk30 utility runs the shell program cl30 on each source file in the archive 
to either compile or assemble it. It then collects all the object files into the out¬ 
put library. All the tools must be in your PATFI. The utility ignores and disables 
the environment variables TMP, C_OPTION, and C_DIR. 


Library Utility Specific Options 

Most of the options that are included on the command line correspond directly 

to options of the same name used with the compiler and assembler. The follow¬ 
ing options apply only to the library-build utility. 

—c extracts C source files contained in the source archive from the 

library and leaves them in the current directory after the utility has 
completed execution. 

—h instructs mk30to use header files contained in the source archive 

and leave them in the current directory after the utility has com¬ 
pleted execution. You will probably want to use this option to install 
the runtime-support header files from the rts.src archive that is 
shipped with the tools. 

—k instructs the mk30 utility to over-write files. By default, the utility 

aborts any time it attempts to create an object file when an object 
file of the same name already exists in the current directory, re¬ 
gardless of whether you specified the name or the utility derived 
it. 

—q instructs mk30 to suppress header information (quiet). 
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—u instructs mk30 not to use the header files contained in the source 

archive when building the object library. If the desired headers are 
already in the current directory, there is no reason to reinstall 
them. This option also gives you some flexibility in modifying 
runtime-support functions to suit your application. 

—v prints progress information to the screen during execution of the 

utility. Normally, the utility operates silently (no screen messages). 

Example: The following command builds the standard runtime support library 
as an object library named rts40r.lib. The library is compiled for the 
TMS320C4x (-v40), optimized with inline function expansion (-x and -o), and 
uses the register-argument runtime conventions. The example assumes that 
the runtime support headers already exist in the current directory (—u). 

mk.30 —u -v40 -o -x -mr rts.src -1 rts40r.lib 


Library-Build Utility 
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6.2 Options Summary 

Options for the mk30 utility correspond directly to the options that the compiler 
uses. These options are described in detail in subsection 2.1.3 on page 2-5. 


General Options 

Effect 

-g 

symbolic debugging 

—V XX 

specify processor TMS320Cxx (v30, v32, v40, v44) 

Parser Options 

Effect 

-pk 

K&R compatible; compatible with previous C standards 

-pw 

suppress warning messages 

-p? 

enable trigraph expansion 

Optimizer Options 

Effect 

-oO 

level 0; register optimization 

—ol 

level 1; level 0 + local optimization 

-o2 (or -o) 

level 2; level 1 + global optimization 

-o3 

level 3; level 2 + file optimization 

-ox (equivalent to -x2) 

defines JNLINE + invokes optimizer at level 2 

Inlining Options 

Effect 

—xl 

default inlining level 

-x2 (or -x) 

defines JNLINE + invokes optimizer at level 2 

Runtime Model Options 

Effect 

-ma 

assumes aliased variables 

-mb 

big memory model 

-me 

fast float to int conversion 

-mf 

far pointers 

-mi 

avoid RPTS loops 

-ml 

runtime support assembly calls use far calls 

-mm 

use MPYI for multiply 

-mn 

enables optimization disabled by -g 

-mp 

perform speed optimizations at cost of increased code 
size 

-mr 

register argument conventions 

-ms 

assume all memory accessible when optimizing 

-mt 

generate Ada compatible frame structure 

-mtc 

generate Tartan LAJ-compatible function prolog 
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Type Checking Options 

Effect 

-tf 

relax prototype checking 

-tp 

relax pointer combination checking 

Assembler Options 

Effect 

-as 

keep labels as symbols 


Library-Build Utility 
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Appendix A 


Description of Compiler Optimizations 


The TMS320C3x/C4x C compiler uses a variety of optimization techniques to 
improve the execution speed of your C programs and to reduce their size. 
Optimization occurs at various levels throughout the compiler. Most of the 
optimizations described here are performed by the separate optimizer pass 
that you enable and control with the -o compiler options. (For details about the 
-o options, refer to Section 2.4 on page 2-38.) However, the code generator 
performs some optimizations, particularly the target-specific optimizations, 
that you cannot selectively enable or disable. 

This appendix describes two categories of optimizations: general and target- 
specific. General optimizations improve any C code, and target-specific 
optimizations are designed especially for the TMS320C3x/C4x architecture. 
Both kinds of optimizations are performed throughout the compiler. Some of 
the examples in this section were compiled with the -v40 option, and some with 
-v30. The code produced will be slightly different different depending on the 
version. Forexample, ExampleA-1 showscodeproducedwiththe-v40option, 
so one of its local variables is assigned to register R8 (a register the ’C3x doesn’t 
have). Unless otherwise noted, the differences between -v30 and -v40 code 
are minimal. 


These are the optimizations covered in this appendix: 


Target-Specific Optimizations 

□ Register variables 

□ Register tracking/targeting 

Q Cost-based register allocation 

□ Autoincrement addressing 

□ Repeat blocks 

□ Parallel instructions 

□ Conditional instructions 

□ Delayed branches 

□ TMS320C4x-specific features 


General Optimizations 

Cl Algebraic reordering, symbolic 
simplification, constant folding 

Q Alias disambiguation 

□ Copy propagation 

□ Common subexpression elimination 

□ Redundant assignment elimination 

□ Branch optimizations, control-flow 
simplification, delayed branches 

□ Loop induction variable optimizations, 
strength reduction 

□ Loop unrolling 

□ Loop rotation 

□ Loop invariant code motion 

□ Inline function expansion 
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Effective register use 

The TMS320C3x/C4x DSPs have a large and versatile set of registers. The 
compiler is designed to make effective use of the registers, for both general 
computations and in cases where specific registers can be used in specialized 
ways. 

□ Register variables 

The compiler helps maximize the use of registers for storing local variables, 
parameters, and temporary values. Variables stored in registers can be 
accessed more efficiently than variables in memory. Register variables are 
particularly effective for pointers. See Example A-1 and Example A-2. 

□ Register tracking/targeting 

The compiler tracks the contents of registers so that it avoids reloading values 
if they are used again soon. Variables, constants, and structure references 
such as (a.b) are tracked through both straight-line code and forward 
branches. The compiler also uses register targeting to compute expressions 
directly into specific registers when required, as in the case of assigning to reg¬ 
ister variables or returning values from functions. See Example A-1. 
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Example A-1. Register Variables and Register Tracking/Targeting 


int gvar; 


reg(int i, 

int ; 

gvar = 

call 

j 

gvar 

return 

j; 


i; 


} 


★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ 

* TMS320C30 C COMPILER Version X 

; ac30 -mr al.c al.if 

; opt30 -r -02 al.if al.opt 

; cg30 -p al.opt al.asm al.tmp 

.version 30 

FP .set AR3 

.globl _gvar 
.globl _reg 

k'k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k 

* FUNCTION DEF : _reg 

* ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★'Jr'*’ 


_reg: 

PUSH R4 

■k 

* R4 assigned to parameter i 

-k 


LDI 

AR2, R4 

CALL 

_call 

AND 

R4,R0,R2 

STI 

R2, @_gvar 

ADD I 

1 : 

R4 , R2,R0 

POP 

R4 


RETS 

.globl _gvar 
.bss _gvar,1 

★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★Tic’ 

* UNDEFINED REFERENCES 

k'k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k'k-k'k 


.globl _call 
. end 


.XX * 


★ 


■k 

'k-k'k'k'k-k-k'k'k'k-k'k 
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□ Cost-based register allocation 

The optimizer, when enabled, allocates registers to user variables and 
compiler temporary values according to their type, use, and frequency. Vari¬ 
ables used within loops are weighted to have priority over others, and those 
variables whose uses don’t overlap may be allocated to the same register. 
Variables with specific requirements are allocated into registers that can 
accommodate them. For example, the compiler tries to allocate loop counters 
into RC. The allocation algorithm also minimizes pipeline conflicts that can 
result from performing calculations using address generation registers in the 
vicinity of indirection. 

□ Passing arguments in registers 

The compiler supports a new, optional calling sequence that passes 
arguments to registers rather than pushing them onto the stack. This can result 
in significant improvement in execution performance, especially if calls are 
important in the application. See Example A-5. 

Autoincrement addressing 

For pointer expressions of the form *p++, *p—, *++p, or * —p, the compil¬ 
er uses efficient TMS320C3x/C4x autoincrement addressing modes. In many 
cases, where code steps through an array in a loop, such as for 
(i = 0 ; i < n; ++i) a [ i ]..., the loop optimizations convert the array 
references to indirect references through autoincremented register variable 
pointers. See Example A-2. 


Repeat blocks 

The TMS320C3x/C4x supports zero-overhead loops with the RPTS 
(repeat single) and RPTB (repeat block) instructions. With the optimizer, the 
compiler can detect loops controlled by counters and generate code for them 
using the efficient repeat forms: RPTS for single-instruction loops, or RPTB for 
larger loops. For both forms, the iteration count can be either a constant or an 
expression. See Example A-2 and Example A-8. 


Parallel instructions 


Several TMS320C3x/C4x instructions such as load/load, store/operate, and 
multiply/add can be paired with each other and executed in parallel. When 
adjacent instructions match the addressing requirements, the compiler 
combines them in parallel. Although the code generator performs this 
optimization, the optimizer greatly increases effectiveness because operands 
are more likely to be in registers. See Example A-2 and Example A-8. 
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Example A-2. Repeat Blocks, Autoincrement Addressing, Parallel Instructions, Strength 
Reduction, Induction Variable Elimination, Register Variables, and Loop 
Test Replacement 


float a[10], b[10]; 
float dot_product () 

{ 

int i; 
float sum; 

for (1=0; i<10; i++) 

sum += a[i] * b[i]; 

return sum 


*★★★**★★*★★★**★★*★★★**★★*★★★**★★*★★★**★★*★★★*★★★*★★★**★★*★★★**★★*★★★**★ 

* TMS320C30 C COMPILER Version X.XX * 

k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k*-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

; ac30 -mr a2.c a2.if 

; opt30 -r -02 a2.if a2.opt 

; cg30 -p a2.opt a2.asm a2.tmp 

.version 30 

FP .set AR3 

.globl _a 
.globl _b 

.globl _dot_product 

•k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k'k'k 

* FUNCTION DEF : _dot_product * 


_dot_product: 

PUSH AR4 

•k 


* R2 assigned to variable sum 

k 


LDI 
LDI 
MPYF 
RPTS 
ADDF 
| | MPYF 
ADDF 
LDF 

EP10_1 : 

POP 

RETS 


0CONST+O,AR4 
0CONST+1,AR2 
*AR2++,*AR4++, R0 
8 

R0, R2 

*AR2++,*AR4++, R0 
R0, R2 
R2, R0 

AR4 


.globl _a 
.bss _a, 10 

.globl _b 
.bss _b,10 

•k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k'k'k 


* DEFINE CONSTANTS * 

k'k'k-k-k-k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k'k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k'k'k 


bss 

CONST,2 


sect 

" . cinit" 


word 

2,CONST 


word 

_a 

; 0 

word 

end 

_b 

; l 
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Conditional instructions 

The load instructions in the TMS320C3x/C4x can be executed conditionally. 
For simple assignments such as 

a = condition ? exprl : expr2 or if (condition) a = b; 

the compiler can use conditional loads to avoid costly branches. 


Delayed branches 


The TMS320C3x/C4x provides delayed branch instructions that can be 
inserted three instructions early in an instruction stream, avoiding costly 
pipeline flushes associated with normal branches. The compiler uses 
unconditional delayed branches wherever possible, and conditional delayed 
branches for counting loops. See Example A-3. 


Example A-3. TMS320C3x/C4x Delayed Branch Instructions 


wait(volatile int *p) 

{ 

for (; ; ) 


} 


if (*p & 0x08) *p |= OxFO 


kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

TMS320C30 C COMPILER Version 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 


k k ★ k k k 

x.xx * 

k k ★ k k k 


FP 

★ ★ 
k 

k ★ 


ac30 -mr a3.c a3.if 
opt30 -r -02 a3.if a3.opt 
cg30 -p a3.opt a3.asm a3.tmp 
.version 30 

.set AR3 

.globl _wait 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

FUNCTION DEF : _wait 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 


k k k k k k 
k 

k k k k k k 


_wait 

k 

* AR2 assigned to parameter p 

k 


LDI 8 , R0 
TSTB R0.*AR2 
BZ L2 
LDI 240,R1 
OR R1,*AR2,R2 

STI R2.*AR2 

B L2 ; BRANCH OCCURS 

. end 
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TMS320C4x-specific features 

The TMS320C4x has several instructions and addressing modes that are 
particularly useful in compiled code. The instructions include store integer 
immediate (STIK), load address register (LDA), load data page pointer 
(LDPK), and a 32x32 integer multiply (MPYI). The new addressing modes 
allow constants and indirect+offset operands to be used in 3-operand 
instructions. In addition, separate AR interlocks eliminate the pipeline delays 
associated with independent use of the AR registers. Example A-4 illustrates 
some of the new ’C4x features. 
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Example A-4. TMS320C4x-Specific Features 


typedef struct S 
sval (s *p) 

{int i, j, k; } s; 

P~>j = 5; 
p->k *= 10; 
return p->i 

1 

I 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ 

* TMS320C30 C COMPILER Version X.XX * 

■k'k'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k'k-k-k'k'k'k 

; ac30 -v40 a4.c a4.if 

; opt30 - 

v40 -02 a4.if a4.opt 

; cg30 -v40 a4.opt a4.asm a4.tmp 

.version 40 

FP . set 

AR3 

.globl 

_sval 

■k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k'k-k'k 

* FUNCTION DEF : 

_sval * 

k■^'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k-k-k-k-k'k-k-k-k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k'k'k-k'k'k'k 

_sval 


PUSH 

FP 

LDI 

SP, FP 

•k 


* AR2 assigned to parameter p 

■k 


LDA 

*-FP,(2),AR2 

STIK 

5, *+AR2 (1) 

MPYI 

10,*+AR2(2),R0 

STI 

R0,*+AR2(2) 

LDI 

*AR2,R0 

EPIO_l: 


LDI 

*-FP(1),R1 

BD 

R1 

LDI 

*FP,FP 

NOP 


SUB1 

2, SP 

B 

R1 ;BRANCH OCCURS 

. end 
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Expression simplification 

For optimal evaluation, the compiler simplifies expressions into equivalent 
forms requiring fewer instructions or registers. For example, the expression 
(a + b) - (c + d) requires 5 instructions and 2 registers to evaluate; it can be 
optimized to ((a + b) - c) - d, which takes only 4 instructions and 1 register. 
Operations between constants are folded into single constants. For example, 
a = (b + 4) - (c + 1) becomes a = b - c + 3. See Example A-5. 

Alias disambiguation 

Programs written in the C language generally use many pointer variables. 
Frequently, compilers are unable to determine whether or not two or more 
I (lowercase L) values (symbols, pointer references, or structure references) 
refer to the same memory location. This aliasing of memory locations often 
prevents the compiler from retaining values in registers, because it cannot be 
sure that the register and memory continue to hold the same values over time. 
Alias disambiguation is a technique that determines when two pointer expres¬ 
sions cannot point to the same location, allowing the compiler to optimize such 
expressions. 
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Data-flow optimizations 

Collectively, the following three data-flow optimizations replace expressions 
with less costly ones, detect and remove unnecessary assignments, and avoid 
operations that produce values already computed. The optimizer performs 
these data flow optimizations both locally (within basic blocks) and globally 
(across entire functions). See Example A-5 and Example A-6. 

□ Copy propagation 

Following an assignment to a variable, the compiler replaces references to 
the variable with its value. The value could be another variable, a constant, 
or a common subexpression. This may result in increased opportunities 
for constant folding, common subexpression elimination, or even total 
elimination of the variable. See Example A-5 and Example A-6. 

□ Common subexpression elimination 

When the same value is produced by two or more expressions, the 
compiler computes the value once, saves it, and reuses it. See 
Example A-5. 

□ Redundant assignment elimination 

Often, copy propagation and common subexpression elimination 
optimizations result in unnecessary assignments to variables (variables 
with no subsequent reference before another assignment or before the 
end of the function). The optimizer removes these dead assignments. See 
Example A-5. 
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Example A-5. Data-Flow Optimizations 


simp(int j) 

{ 

int a = 3; 

int b = (j * a) + (j * 2); 
int c = (j « a); 
int d = (j « 3) + (j << b); 
call(a,b,c, d) ; 


* TMS320C30 C COMPILER 


Version X.XX 


; ac30 -mr a5.c a5.if 

; opt30 -r -02 a5.if a5.opt 

; cg30 -p a5.opt a5.asm a5.tmp 

version 30 

FP .set AR3 

.globl _simp 


* FUNCTION DEF : _simp 


_simp 

* AR2 assigned to parameter j 

★ 

LDI 2, R0 

LSH R0,AR2,R1 
ADD I R1,AR2,R2 

LDI 3, R1 

LSH R1,AR2,R3 
LSH R2 , AR2,RC 

ADDI R3, RC 

LDI 3, AR2 

CALL _call 

EPIO_l: 

RETS 


* UNDEFINED REFERENCES 


.globl _call 
. end 
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Branch optimizations / control-flow simplification 

The compiler analyzes the branching behavior of a program and rearranges 
the linear sequences of operations (basic blocks) to remove branches or 
redundant conditions. Unreachable code is deleted, branches to branches are 
bypassed, and conditional branches over unconditional branches are 
simplified to a single conditional branch. When the value of a condition can be 
determined at compile time (through copy propagation or other data flow anal¬ 
ysis), a conditional branch can be deleted. Switch case lists are analyzed in 
the same way as conditional branches and are sometimes eliminated entirely. 
Some simple control-flow constructs can be reduced to conditional instruc¬ 
tions, totally eliminating the need for branches. See Example A-6. 
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Example A-6. Copy Propagation and Control-Flow Simplification 


f sm () 


enum { ALPHA, 
int *input; 

BETA, GAMMA 

OMEGA } 

state 

= ALPHA; 



while (state ! 

= OMEGA) 






switch (state) 






i 

case ALPHA 

: state = ( 

*input++ 

== 0 ) 

? BETA: 

GAMMA; 

break 

case BETA 

: state = ( 

*input++ 

== 0 ) 

? GAMMA: 

ALPHA; 

break 

case GAMMA 

: state = ( 

*input++ 

== 0 ) 

? GAMMA: 

OMEGA; 

break 


} 


* TMS320C40 C COMPILER Version X.XX* 

; ac30 -v40 a6.c a6.if 

; opt30 -v40 -02 a6.if a6.opt 

; cg30 -v40 a6.opt a6.asm a6.tmp 

.version 40 

FP .set AR3 

.globl _fsm 

★ ★★★ 'k-k'k-k-k-k'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k-k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k-k'k-k-k-k'k-k-k'k'k-k-k'k-k'k-k'k'k-k-k-k'k-k-k-k'k 

* FUNCTION DEF : _fsm * 

★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ 

_f sm 
★ 

* AR2 assigned to variable input 

* 

LDI *AR2 + + , R0 
BNZ L4 

L2 : 

LDI *AR2 + + , R0 
BZ L4 

LDI AR2 + + , R0 
BZ L2 

L4 : 

LDI *AR2++, R0 
BZ L4 

EPIO_l: 

RETS 
. end 


Loop induction variable optimizations / strength reduction 

Loop induction variables are variables whose value within a loop is directly 
related to the number of executions of the loop. Array indices and control vari¬ 
ables of for loops are very often induction variables. Strength reduction is the 
process of replacing costly expressions involving induction variables with 
more efficient expressions. For example, code that indexes into a sequence 
of array elements is replaced with code that increments a pointer through the 
array. Loops controlled by incrementing a counter are written as 
TMS320C3x/C4x repeat blocks or by using efficient decrement-and-branch 


Description of Compiler Optimizations 


A-13 




Description of Compiler Optimizations 


instructions. Induction variable analysis and strength reduction together often 
remove all references to your loop control variable, allowing it to be eliminated 
entirely. See Example A-2 and Example A-8. 


Loop Unrolling 


When the compiler can determine that a short loop is executed a low, constant 
number of times, it replicates the body of the loop rather than generating the 
loop. This avoids any branches or use of the repeat registers. (“Low” and 
“short” are subjective judgments made by the compiler.) See Example A-7. 

Example A-7. Loop Unrolling 


add3(int a[3]) 

{ 

int i, sum = 0; 

for (i=0; i<3; i++) sum += a[i] 
return sum; 

} 

* TMS320C30 C COMPILER Version X.XX* 


FP 

★ ★ ★ ★ 
•k 

k ~k -k -k 


ac30 a7.c a7.if 
opt30 -02 a7.if a7.opt 
cg30 a7.opt a7.asm a7.tmp 
.version 30 

. set AR3 

.globl _add3 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ 
FUNCTION DEF : _add3 * 

k'k-k-k-k'k'k-k-k'k'k-k-k'k-k-k-k-k'k-k-k'k-k-k-k'k-k-k-k'k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k'k-k-k'k'k'k-k'k-k-k-k-k-k-k-k-k-k-k-k'k'k 


_add3: 

PUSH FP 

LDI SP, FP 

k 


* R2 assigned to variable sum 

k 


EPIO_l: 


k ~k -k 


LDI *—FP(2),AR2 

LDI 0,R2 

ADDI *AR2++,R2 

ADDI *AR2++,R2 

ADDI *AR2, R2 

LDI R2,R0 

LDI *—FP (1) , R1 

BD R1 

LDI *FP,FP 

NOP 

SUBI 2, SP 

B R1 ;BRANCH OCCURS 

. end 
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Loop rotation 


The compiler evaluates loop conditionals at the bottom of loops, saving a cost¬ 
ly extra branch out of the loop. In many cases, the initial entry conditional check 
and the branch are optimized out. 


Loop invariant code motion 

This optimization identifies expressions within loops that always compute the 
same value. The computation is moved in front of the loop, and each occur¬ 
rence of the expression in the loop is replaced by a reference to the 
precomputed value. See Example A-8. 


Inline function expansion 

The special keyword inline directs the compiler to replace calls to a function 
with inline code, saving the overhead associated with a function call as well as 
providing increased opportunities to apply other optimizations. See 
Example A-8 and Example A-9. The optimizer inlines small functions not de¬ 
clared as inline when invoked with the -o3 option. The size of code growth al¬ 
lowed may be changed using the -oi size option. 

Example A-8. Inline Function Expansion, part one 

inline blkcpy (char *to, char ‘from, int n) 

{ 

if (n > 0 ) 

do *to++ = *from++; while (—n != 0); 

} 

struct s {int a , b, c[10]; }; 

initstr (struct s *ps, char t [12]) 

{ 

blkcpy((char *)ps, t, 12); 

} 
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Example A-9. Inline Function Expansion, part two 


*1?j?ic*1?1?ic*1?j?ic**j?'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k'k-k-k'k 

* TMS320C30 C COMPILER Version X.XX * 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ 

; ac30 -mr a8.c a8.if 

; opt30 -r -02 a8.if a8.opt 

; cg30 -p a8.opt a8.asm a8.tmp 

.version 30 

FP .set AR3 

.globl _blkcpy 

■k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k'k 

* FUNCTION DEF : _blkcpy * 


blkcpy: 

PUSH AR4 


R3 

assigned 

to 

parameter 

n 

AR2 

assigned 

to 

parameter 

to 

AR4 

assigned 

to 

parameter 

from 



LDI 

R2,AR4 


CMP I 

0, R3 


BLE 

EPI0_1 


LDI 

R3, RC 


SUBI 

1, RC 


RPTB 

L5 


LDI 

*AR4++,R0 

L5 : 

STI 

R0,*AR2++ 

EP10_1 




POP 

AR4 


RETS 



.globl 

_initstr 

•k-k-k-k'k'k-k-k'k'k-k-k-k-k-k-k-k-k-k-k'k'k-k-k-k-k-k-k-k'k-k-k' 

* FUNCTION DEF : _initstr 


_initstr 



PUSH 

AR4 

* AR2 

assigned to parameter ps 

* AR2 

assigned to variable to 

* AR4 

assigned to parameter to 

* AR4 

assigned to variable from 


LDI 

R2,AR4 


* >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>ENTERING blkcpy() 


LDI 

*AR4++,R0 

RPTS 

10 

STI 

R0,*AR2++ 

LDI 

*AR4++,R0 

STI 

R0,*AR2++ 

POP 

AR4 

RETS 


. end 
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The C I/O Functions 


Some of the tasks that a C program performs (such as I/O, dynamic memory 
allocation, string operations, and trigonometric functions) are not part of the 
C language itself. However, the ANSI C standard defines a set of runtime- 
support functions that perform these tasks. The TMS320C3x/C4x C compiler 
implements the complete ANSI standard library, except for those facilities that 
handle exception conditions and locale issues (properties that depend on local 
language, nationality, or culture). Using the ANSI standard library ensures a 
consistent set of functions that provide for greater portability. 

In addition to the ANSI-specified functions, the TMS320C3x/C4x runtime- 
support library includes routines that give you direct C language I/O requests. 


Topic Page 


B.1 

Using the I/O Functions . 

R-? 

B.2 

Overview of Low-Level I/O Implementation. 

R-3 

B.3 

Adding a Device For C I/O . 

B-5 
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B.1 Using the I/O Functions 

The C I/O functions make it possible to access the host’s operating system to 
perform I/O (using the debugger). For example, printf statements executed in 
a program appear in the debugger command window. When used in 
conjunction with the debugging tools, the capability to perform I/O on the host 
gives you more options when debugging and testing code. 

To use the I/O functions: 

□ Include the header file stdio.h for each module that references a function. 

With properly written device drivers, the library also offers facilities to perform 
I/O on a user-specified device. 

If there is not enough space on the heap for a C I/O buffer, buffered operations 
on the file will fail. If a call to printf() mysteriously fails, this may be the reason. 
Check the size of the heap. To set the heap size, use the -heap option when 
linking. For information on the -heap option, see the Linker Description 
chapter of the TMS320C3x/C4x Assembly Language Tools User’s Guide. 

For example, given the following program in a file named main.c: 

#include <stdio.h> 

main () 

{ 

FILE *fid; 

fid = fopen("myfile","w"); 
fprintf(fid,"Hello, worldXn"); 
fclose(fid); 

printf("Hello again, worldXn"); 

} 

Issuing the following shell command compiles, links, and creates the file 
main.out: 

cl30 main.c -z -heap 400 -1 rts.lib -o main.out 

Executing main.out under the debugger on a SPARC host accomplishes the 
following: 

1) Opens the file myfile in the directory where the debugger was invoked 

2) Prints the string Hello, world into that file 

3) Closes the file 

4) Prints the string Hello again, world in the debugger command window 
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B.2 Overview of Low-Level I/O Implementation 

The code that implements I/O is logically divided into layers: high level, low 
level, and device level. 

The high-level functions are the standard C library of stream I/O routines 
(printf, scant, fopen, getchar, and so on). These routines map an I/O request 
to one or more of the I/O commands that are handled by the low-level routines. 

The low-level routines are comprised of basic I/O functions: OPEN, READ, 
WRITE, CLOSE, LSEEK, RENAME, and UNLINK. These low-level routines 
are declared in file.h and provide the interface between the high-level 
functions and the device-level drivers that actually perform the I/O command 
on the specified device. 

The low-level functions also define and maintain a stream table that 
associates a file descriptor with a device. The stream table interacts with the 
device table to ensure that an I/O command performed on a stream executes 
the correct device-level routine. 

The data structures interact as shown in Figure B-1. 

Figure B-1. Interaction of Data Structures in I/O Functions 

Stream table Device table 

file_descriptor1 
file_descriptor2 
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Overview of Low-Level I/O Implementation 


The first three streams in the stream table are predefined to be stdin, stdout, 
and stderr, and they point to the host device and associated device drivers. 


Figure B-2. The First Three Streams in the Stream Table 


Stream table Device table 


file_descriptor1 

file_descriptor2 

file_descriptor3 




open 

read 



open 

read 


At the next level are the user-definable device-level drivers. They map directly 
to the low-level I/O functions. The runtime-support library includes the device 
drivers necessary to perform I/O on the host on which the debugger is running. 

The specifications for writing device-level routines to interface with the low- 
level routines are shown on pages B-7 to B-10. Each function must set up and 
maintain its own data structures as needed. Some function definitions perform 
no action and just return. 
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B.3 Adding a Device For C I/O 

The low-level functions provide facilities that allow you to add and use a device 
for I/O at runtime. The procedure for using these facilities is: 

1) Define the device-level functions as described in subsection B.2, 
Overview of Low-Level I/O Implementation, on page B-3. 


I-1 

Note: Use Unique Function Names 

The function names, OPEN, CLOSE, READ, and so on, are used by the low- 

level routines. Use other names for the device-level functions that you write. 

I_I 

2) Use the low-level function add_device() to add your device to the 
device_table. The device table is a statically-defined array that supports 
n devices, where n is defined by the macro _NDEVICE found in stdio.h. 
The structure representing a device is also defined in stdio.h and is 
composed of the following fields: 


name 

is the string for device name. 

flags 

specifies whether the device supports multiple 
streams or not. 

function pointers 

are pointers to the device-level functions: 

□ CLOSE 

□ LSEEK 

□ OPEN 

□ READ 

□ RENAME 

□ WRITE 

□ UNLINK 


The first entry in the device table is predefined to be the host device on 
which the debugger is running. The low-level routine add_device() finds 
the first empty position in the device table and initializes the device fields 
with the passed-in arguments. For a complete description, see the 
add_device function on page 5-23. 

3) Once the device is added, call fopen() to open a stream and associate it 
with that device. Use devicename:filename as the first argument to 
fopenQ. 
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The following program illustrates adding and using a device for C I/O: 

#include <stdio.h> 

/****************************************************************************/ 
/* Declarations of the user-defined device drivers */ 

/****************************************************************************/ 
extern int my_open(char *path, unsigned flags, int fno); 
extern int my_close(int fno); 

extern int my_read(int fno, char *buffer, unsigned count); 
extern int my_write(int fno, char *buffer, unsigned count); 
extern int my_lseek(int fno, long offset, int origin); 
extern int my_unlink(char *path); 

extern int my_rename(char *old_name, char *new_name); 
main () 

{ 

FILE *f id; 

add_device("mydevice", _MSA, my_open, my_close, my_read, my_write, my_lseek, 

my_unlink, my_rename); 

fid = fopen("mydevice:test", "w") ; 
fprintf(fid, "Hello, world\n"); 

fclose(fid); 

} 
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Alphabetical Summary of C I/O Functions CLOSE, LSEEK 


CLOSE 


Syntax 

Description 

Return Value 


LSEEK 


Syntax 

Description 


Return Value 


Close File or Device For I/O 


int CLOSE(int file_descriptot); 

The CLOSE function closes the device or file associated with file_descriptor. 

The file_descriptor\s the stream number assigned by the low-level routines 
that is associated with the opened device or file. 

The function returns one of the following values: 

0 if successful 
-1 if fails 

Set File Position Indicator 


long LSEEK(int file_descriptor, long offset, int origin ); 

The LSEEK function sets the file position indicator for the given file to origin 
+ offset. The file position indicator measures the position in characters from 
the beginning of the file. 

□ The file_descriptor is the stream number assigned by the low-level 
routines that the device-level driver must associate with the opened file or 
device. 

□ The offset indicates the relative offset from the origin in characters. 

□ The origin is used to indicate which of the base locations the offset is 
measured from. The origin must be a value returned by one of the follow¬ 
ing macros: 

SEEK_SET (0x0000) Beginning of file 

SEEK_CUR (0x0001) Current value of the file position indicator 

SEEK END (0x0002) End of file 

The function returns one of the following values: 

# new value of the file-position indicator if successful 
EOF if fails 
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OPEN Alphabetical Summary of C I/O Functions 


OPEN 


Syntax 

Description 


Return Value 


Open File or Device For I/O 


int OPEN(char *path, unsigned flags, int mode); 

The OPEN function opens the device or file specified by path and prepares it 
for I/O. 

□ The path is the filename of the file to be opened, including path 
information. 

□ The flags are attributes that specify how the device or file is manipulated. 
The flags are specified using the following symbols: 


0_ 

_RD0NLY 

(0x0000) 

/* 

open 

for 

reading */ 


o_ 

_WR0NLY 

(0x0001) 

/* 

open 

for 

writing */ 


o_ 

_RDWR 

(0x0002) 

/* 

open 

for 

read & write 

*/ 

o_ 

.APPEND 

(0x0008) 

/* 

append on 

each write * 

/ 

0_ 

_CREAT 

(0x0100) 

/* 

open 

with 

file create 

*/ 

0_ 

_TRUNC 

(0x0200) 

/* 

open 

with 

truncation * 

/ 

o_ 

1 

H 

PQ 

(0x8000) 

/* 

open 

in binary mode */ 



These parameters can be ignored in some cases, depending on how data 
is interpreted by the device. Note, however, that the high-level I/O calls 
look at how the file was opened in an fopen statement and prevent certain 
actions, depending on the open attributes. 

□ The mode is required but ignored. 

The function returns one of the following values: 

# stream number assigned by the low-level routines that the device-level 
driver associates with the opened file or device if successful 

<0 if fails 
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Alphabetical Summary of C I/O Functions READ, RENAME 


READ 


Syntax 

Description 


Return Value 


RENAME 


Syntax 

Description 

Return Value 


Read Characters From Buffer 


int READ(int file_descriptor, char *buffer, unsigned count); 

The READ function reads the number of characters specified by count to the 
buffer from the device or file associated with file_descriptor. 

□ The file_descriptor is the stream number assigned by the low-level 
routines that is associated with the opened file or device. 

□ The buffer is the location of the buffer where the read characters are 
placed. 

□ The count is the number of characters to read from the device or file. 

The function returns one of the following values: 

0 if EOF was encountered before the read was complete 
# number of characters read in every other instance 
-1 if fails 


Rename File 


int RENAME(char *old_name, char *new_name ); 
The RENAME function changes the name of a file. 

□ The old_name is the current name of the file. 

□ The new_name is the new name for the file. 

The function returns one of the following values: 

0 if the rename is successful 
Non-0 if it fails 
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UNLINK, WRITE Alphabetical Summary of C I/O Functions 


UNLINK 

Delete File 

Syntax 

int UNLINK(char *path)\ 

Description 

The UNLINK function deletes the file specified by path. 

The path is the filename of the file to be opened, including path information. 

Return Value 

The function returns one of the following values: 

0 if successful 

-1 if fails 


Write Characters to Buffer 

Syntax 

int WRITE(int file_descriptor, char *buffer, unsigned count)-, 

Description 

The WRITE function writes the number of characters specified by count from 
the buffer to the device or file associated with file_descriptor. 

□ The file_descriptor is the stream number assigned by the low-level 
routines that is associated with the opened file or device. 

□ The buffer is the location of the buffer where the write characters are 
placed. 

□ The count is the number of characters to write to the device or file. 

Return Value 

The function returns one of the following values: 

# number of characters written is successful 

-1 if fails 
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Glossary 



aliasing: a method of accessing a single data object in more than one way, 
as when a pointer points to a named object. The optimizer has logic to 
detect aliasing, but aliasing can cause problems for the optimizer. 

allocation: A process in which the linker calculates the final memory 
addresses of output sections. 

archive library: A collection of individual files that have been grouped into 
a single file. 

archiver: A software program that allows you to collect several individual 
files into a single file called an archive library. The archiver also allows 
you to delete, extract, or replace members of the archive library, as well 
as to add new members. 

assembler: A software program that creates a machine-language program 
from a source file that contains assembly language instructions, 
directives, and macro directives. The assembler substitutes absolute 
operation codes for symbolic operation codes, and absolute or 
relocatable addresses for symbolic addresses. 

assignment statement: A statement that assigns a value to a variable. 

autoinitialization: The process of initializing global C variables (contained 
in the .cinit section) before beginning program execution. 



binding: Associating or linking together two complementary software 
objects. 

block: A set of declarations and statements that are grouped together with 
braces. 
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Glossary 


.bss: One of the default COFF sections. You can use the .bss directive to 
reserve a specified amount of space in the memory map that can later 
be used for storing data. The .bss section is uninitialized. 



C compiler: A program that translates C source statements into 
TMS320C3x/C4x assembly language source statements. 

COFF (common object file format): A binary object file format that 
promotes modular programming by supporting the concept of sections. 

comment: A source statement (or portion of a source statement) that is 
used to document or improve readability of a source file. Comments are 
not compiled, assembled, or linked; they have no effect on the object file. 

constant: A numeric value that can be used as an operand. 

cross-reference lister: A debugging tool that accepts linked object files as 
input and produces cross-reference listings as output. 

cross-reference listing: An output file created by the assembler that lists 
the symbols that were defined, what line they were defined on, which 
lines referenced them, and their final values. 



.data: One of the default COFF sections. The .data section is an initialized 
section that contains initialized data. You can use the .data directive to 
assemble code into the .data section. 

directive: Special-purpose commands that control the actions and 
functions of a software tool (as opposed to assembly language 
instructions, which control the actions of a device). 



environment variables: System symbols that you define and assign to a 
string. They are usually included in various batch files; for example, in 
AUTOEXEC.BAT. 

entry point: The starting execution point in target memory. 

executable module: An object file that has been linked and can be 
executed in a TMS320 system. 
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Glossary 


expression: A constant, a symbol, or a series of constants and symbols 
separated by arithmetic operators. 



field: For the TMS320, a software-configurable data type whose length can 
be programmed to be any value in the range of 1-16 bits. 



global: A kind of symbol that is either 1) defined in the current module and 
accessed in another, or 2) accessed in the current module but defined 
in another. 



high-level language debugging: The ability of a compiler to retain 
symbolic and high-level language information (such as type and function 
definitions) so that a debugging tool can use this information. 

hole: An area between the input sections that compose an output section 
that contains no actual code or data. 



initialized section: A COFF section that contains executable code or 
initialized data. An initialized section can be built up with the .data, .text, 
or .sect directive. 

input section: A section from an object file that will be linked into an 
executable module. 



K & R: The C Programming Language (second edition), by Brian Kernighan 
and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, 
New Jersey, 1988. This book describes ANSI C and is used as a refer¬ 
ence in this book. Paragraphs within the book are referred to with this 
symbol: §. 



Glossary 
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Glossary 


label: A symbol that begins in column 1 of a source statement and 
corresponds to the address of that statement. 

linker: A software tool that combines object files to form an object module 
that can be allocated into TMS320 system memory and executed by the 
TMS320. 

listing file: An output file, created by the assembler, that lists source 
statements, their line numbers, and their effects on the SPC. 

loader: A device that loads an executable module into TMS320 system 
memory. 


M 


macro: A user-defined routine that can be used as an instruction. 

macro call: The process of invoking a macro. 

macro definition: A block of source statements that define the name and 
the code that make up a macro. 

macro expansion: The source statements that are substituted for the 
macro call and are subsequently assembled. 

map file: An output file, created by the linker, that shows the memory 
configuration, section composition, and section allocation, as well as 
symbols and the addresses at which they were defined. 

member: The elements or variables of a structure, union, archive, or 
enumeration. 

memory map: A map of TMS320 target system memory space, which is 
partitioned off into functional blocks. 



object file: A file that has been assembled or linked and contains 
machine-language object code. 

object library: An archive library made up of individual object files. 

operand: The arguments, or parameters, of an assembly language 
instruction, assembler directive, or macro directive. 


C-4 


options: Command parameters that allow you to request additional or 
specific functions when you invoke a software tool. 



Glossary 


output module: A linked, executable object file that can be downloaded and 
executed on a target system. 

output section: A final, allocated section in a linked, executable module. 



protected mode: Thirty-two bit extended DOS mode. These programs re¬ 
quire an extended memory manager and will run only on larger proces¬ 
sors (’386 or better). They can utilize all the available RAM on the com¬ 
puter. 



RAM model: An autoinitialization model used by the linker when linking C 
code. The linker uses this model when you invoke the linker with the 
-cr option. The RAM model allows variables to be initialized at load time 
instead of runtime. 

real mode: Sixteen-bit native MS-DOS mode. This mode limits the available 
memory to 640K. Calls to DOS may involve switching from protected to 
real mode. 

ROM model: An autoinitialization model used by the linker when linking C 
code. The linker uses this model when you invoke the linker with the 
-c option. In the ROM model, the linker loads the .cinit section of data 
tables into memory, and variables are initialized at runtime. 



section: A relocatable block of code or data that will ultimately occupy 
contiguous space in the TMS320 memory map. 

section header: A portion of a COFF object file that contains information 
about a section in the file. Each section has its own header; the header 
points to the section’s starting address, contains the section’s size, etc. 

static: A kind of variable whose scope is confined to a function or a program. 
The values of static variables are not discarded when the function or 
program is exited; their previous value is resumed when the function or 
program is re-entered. 

structure: A collection of one or more variables grouped together under a 
single name. 


Glossary 
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symbol: A string of alphanumeric characters that represents an address or 
a value. 

symbolic debugging: The ability of a software tool to retain symbolic 
information so that it can be used by a debugging tool such as a simulator 
or an emulator. 

symbol table: A portion of a COFF object file that contains information 
about the symbols that are defined and used by the file. 


uninitialized section: A COFF section that reserves space in the TMS320 
memory map but that has no actual contents. These sections are built 
up with the .bss and .usect directives. 

union: A variable that may hold (at different times) objects of different types 
and sizes. 

unsigned: A kind of value that is treated as a positive number, regardless 
of its actual sign. 


virtual memory : The ability for a program to use more memory than a com¬ 
puter actually has available as RAM. This is accomplished by using a 
swap file on disk to augment RAM. When RAM is not sufficient, part of 
the program is swapped out to a disk file until it is needed again. The com¬ 
bination of the swap file and available RAM is the virtual memory. The 
TMS320C3x/C4x tools use a memory extender to provide virtual 
memory management. This memory extender is not provided as an 
executable but is embedded in several of the object programs. 


word: A 32-bit addressable location in target memory. 
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Summary of Updates in This Document 


This appendix provides a summary of the updates in this version of the docu¬ 
ment. Updates within paragraphs appear in a bold typeface. 
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Page: 

2-6 

2-6 


2-62 


Change or Add: 

Add one row (-msrevx) s to the General Shell Option section of Table 2-1, Compiler 
Options Summary Table. 


Add note (see also -msrev) to the -vxx option 


General Shell Options 

Option 

Effect 

These options control the 

-@fiiename 

causes the compiler shell to read 

overall operation of the 


options from the specified file 

cl30 shell. For more 
information, see page 

-c 

no linking (negates -z) 

2-11. 

-dname[=def] 

predefine a constant 


-g 

enable symbolic debugging 


-i dir 

define #include search path 


-k 

keep .asm file 


-msrevx 

specifies the silicon revision of the 
target chip to enable additional func¬ 
tionality for more recent silicon re¬ 
leases. Used in conjunction with -v 
flag. 

Example: 

-msrev6 -v31 : enable new (1996) 
’C31 parallel instructions 
-msrev2 - v32 : enable new (1996) 
’C32 parallel instructions 


-n 

compile only (create .asm file) 


-q 

suppress progress messages (quiet) 


-qq 

suppress all messages (super quiet) 


-s 

interlist optimizer comments and 
assembly source statements if avail¬ 
able; otherwise interlist C and 
assembly source statements 


-ss 

interlist C and assembly source 
statements 


-u name 

undefine a constant 


-vxx 

specify processor; xx = 30, 31,32, 

40, or 44 (default is -v30) (see also 
-msrev) 


-z 

enable linking (all options following 
are passed to linker) 


Specify silicon revision (see -msrev in shell) 
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3.1. Keywords 

Page: Change or Add: 

3-1 Add Section 3.3, Keywords, to the mini table of contents. 

3-7 Add Section 3.3, Keywords, with subsection cregister Keyword and subsection near 

and far keywords. 

3.1.1 The cregister Keyword 

The TMS320C3x/C4x compiler extends the C language by adding the cregis¬ 
ter keyword to allow high level language access to control registers. 

When you use the cregister keyword on an object, the compiler compares the 
name of the object to a list of standard control registers for the ’C3x/C4x (see 
Table 3-2). If the name matches, the compiler generates the code to reference 
the control register. If the name does not match, the compiler issues an error. 

Table 3-2. Valid Control Registers 


Register 

Description 

IE 

CPU/DMS interrupt enable register 

IF 

CPU interrupt flag register 

IOF 

I/O flags 

ST 

Status register 


The cregister keyword can only be used in file scope. The cregister keyword 
is not allowed on any declaration within the boundaries of a function. It can only 
be used on objects of type integer or pointer. The cregister keyword is not al¬ 
lowed on objects of any floating-point type or on any structure or union object. 

The cregister keyword does not imply that the object is volatile. If the control 
register being referenced is volatile (that is, can be modified by some external 
control), then the object should be declared with the volatile keyword also. 

To use a control register in Table 3-2, you must declare each register (with or 
without volatile) as follows: 

extern cregsiter volatile unsigned int register; 

Once you have declared the register, you can use the register name directly. 
See TMS320C3x/C4x CPU and Instruction Set Reference Guide for detailed 
information on the control registers. 
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Example 3-1. Define and Use Control Registers 


extern 

cregisger 

volatile 

unsigned 

int 

IE; 

extern 

cregister 

volatile 

unsigned 

int 

IF; 

extern 

cregisger 

volatile 

unsigned 

int 

IOF; 

extern 

cregister 

volatile 

unsigned 

int 

ST; 

unsigned myfunc 

/ 

(unsigned 

int mask) 




while (ST 

& mask == 

0) 




/* 

Do nothing; wait 

*7; 


t 

return IOF; 





3.3.2 The near and far Keywords 

The ’C3x/C4x C compiler extends the C language with the near and far key¬ 
words to specify how global and static variables are accessed and how func¬ 
tions are called. 

Syntactically, the near and far keywords are treated as storage class modifiers. 
They can appear before, after, or in between the storage class specifiers and 
types. Two storage class modifiers cannot be used together in a single decla¬ 
ration. For example, the following are legal uses: 

far static int x; 
static near int x; 
static int far x; 
far int foo (); 
static far int foo () 


Near and far data objects 

Global and static data objects can be accessed in the following two ways: 

near keyword The compiler assumes that the data item can be accessed 
relative to the data page pointer. For example: 

sti ro, @_var 

far keyword The compiler cannot access the data item via the dp. This 
can be required if the total amount of program data is larger 
than the offset allowed (32K) from the DP. For example: 

ldiu @cll, aro 
sti ro, *aro 

where ell in the .bss holds the address of the variable. 
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By default, the compiler generates small-memory model code, which means 
that every data object is handled as if it were declared near, unless it is actually 
declared far. If an object is declared near, it is normally loaded using relative 
offset addressing from the data page pointer (DP, which is B14). DP points to 
the beginning of the .bss section. If the options-ml, -mb, or-mf are used, the 
default assumptions change. See those options for how their usage changes 
the defaults of the standard memory model. 

If you use the DATA_SECTION pragma, the object is indicated as a far vari¬ 
able, and this cannot be overridden. This ensures access to the variable, since 
the variable might not be on the same data page as the .bss section. See sec¬ 
tion 3.5.2, The DATA_SECTIONpragma, on page 3-13. 

Near and far function calls 

Function calls can be invoked in one of two ways: 

near keyword The compiler assumes that the destination of the call is 
within 2 24 bytes of the caller. Here, the compiler uses the 
PC-relative call instruction. 

call _func 

far keyword The compiler is told by the user that the call is not within 2 24 

bytes of the caller, and the compiler uses the register ad¬ 
dressing mode of the call instruction. 

ldiu @cll, ro 
callu ro 


where constant ell in the .bss holds the address of the function. 

By default, the compiler generates small-memory model code, which means 
that every function call is handled as if it were declared near, unless it is actu¬ 
ally declared far. The default changes, however, when options -ml, -mf, or 
-mb are used. 
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Page: 

4-31 


B-2 


Change or Add: 

Change the last four lines of the EXIT code example. 

Exit 


POP 

AR4 

; restore 

AR4 



POPF 

R4 

; restore 

upper 

32 bits of 

R4 

POP 

R4 

; restore 

lower 

32 bits of 

R4 

POPF 

R3 

; restore 

upper 

32 bits of 

R3 

POP 

R3 

; restore 

lower 

32 bits of 

R3 

SUBI 

2, SP 

; deallocate local frame 


POP 

FP 

; restore 

Frame 

Pointer 


POP 

reti 

ST 

; restore 

STatus 

register 



Cut the second bullet for the Using the I/O Functions section. 
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Page: Change or Add: 

The following is the list of known bugs fixed for this release, R5.10. Please refer to the ap¬ 
propriate contact on the If You Need Assistance page of this manual for more information. 


Bug number 

Description 

SDSsq02943 

How should the SET COND bit be set in the C4x ST reg for the C Com¬ 
piler? 

SDSsq03255 

Passing -g to asm30 does not work with current Debuggers 

SDSsq03762 

Command file for Ink30 does not allow embedded in file name 

SDSsq03767 

Archiver does not allow a default .obj extension 

SDSsq03797 

.sym debug information contains wrong offset 

SDSsq03799 

get incorrect results for long doubles divide operation 

SDSsq03814 

TMS320C3x User’s Guide documents -gsrev6 switch 

SDSsq03879 

Codegen creates illegal parallel instruction subf3 || stf 

SDSsq03888 

Compiler generate “decomposition error” on sample code 

SDSsq03890 

Logical AND operator bug in v. 5.00, works ok in v. 4.70 

SDSsq03897 

optimization level 2 is not as effective as optimization level 1. 

SDSsq03908 

Optimization appears to use direct instead of indirect addressing 

SDSsq03910 

Hex3—byte option, doesn’t work with 5.0, worked fine with 4.7 see 
detail file’s. 

SDSsq03921 

C Compiler generates wrong Assembly code for the #line Statement 

SDSsq03982 

COMPILER ERROR: Unsupported constant operand for LDP 

SDSsq03985 

optimizer generates wrong starting address for structure element 

SDSsq03988 

When linking a debugger MemBIk Save .obj file, » out of memory, 
aborting 

SDSsq03993 

Assembler Generates incorrect “P” parallel-addressing mode 01 
instead of 11; MPYF3||SUBF3 

SDSsq04019 

Far function call generates invalid addresses in big memory configura¬ 
tion 

SDSsq04024 

Compiler removes circular buffer references from asm (“ ”) statements 

SDSsq04084 

pragma DATA_SECTION generates code incorrectly for v5.0 when 
small mem model 
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Bug number 

Description 

SDSsq04151 

The year, tm_year, in ret.src will print as 3 digits after year 2000 

SDSsq04155 

Compiler generates incorrect code using register passing model. 

SDSsq04164 

PRTS30 macros for SWW control are incorrect 

SDSsq04166 

Compiler allocating RS/RC/RE inside c_intxx()’s 

SDSsq04172 

C4x 32-Bit FP Divide Routine DIV_F40 has error 

SDSsq04373 

Codegen adds errant adds into assembly code 

SDSsq04202 

With -mf, compiler generates bad shifts 

SDSsq04215 

Incorrect code generated for calls to ISR and functions; ST not popped 
last 

SDSsq04219 

compiler code calls MODJ40 instead of MODJJ40 

SDSsq04227 

Incorrect code generated for array reference using -o2 

SDSsq04261 

INCOMPATIBLE ADDRESSING MODES generated with -02 switch 
used 

SDSsq04296 

Assembler swaps operands for MPYF3 | ADDF3 

SDSsq04298 

RTS has general errors/nuisances 

SDSsq04301 

Compiler inserts unneeded .aligns into .const section, wastes space 

SDSsq04257 

Compiler uses inefficient FP divide vs 4.70 

SDSsq04338 

Compiler is generating illegal code 

SDSsq04378 

Compiler does not account for second word of long double when opti¬ 
mizing 
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Page: Change or Add: 

The following is the list of bugs closed for this release 


Bugs 

Description 

SDSsq02750 

Enhancement request for error and warning summary 

SDSsq02751 

Request to change the function of the block keyword 

SDSsq02917 

Documentation incomplete 

SDSsq02633 

Problem with STF; Need option to do RND before STF 

SDSsq02964 

ISR's should use more ARx’s than Rx’s to reduce push/pops 

SDSsq02965 

switch (var & 7) generates useless default case 

SDSsq02966 

data & prog on same page = direct addressing 

SDSsq02967 

Allow assembly DATA in non-standard sections 

SDSsq02969 

Assembler should warn of possible parallelism 

SDSsq03152 

Add capabilities to support quoted strings in packed .string ASM directv 

SDSsq03153 

Add capability for packed char/int arrays to save memory 

SDSsq03247 

Sometimes the map and stdout do not report eh .cinit section. 

SDSsq03257 

Wants to be able to use a C header to make assembly .struct directives 

SDSsq03258 

Optimize the c_intxx() functions 

SDSsq03333 

customer has problem compiling following code with v4.70 

SDSsq03492 

strtod() function does not give accurate results 

SDSsq03570 

Invalid Divide Routine 

SDSsq03644 

Request for compiler to be able to place init data in named sections 

SDSsq03645 

Request for compiler to allow packed bytes 

SDSsq03788 

Symbol “pinit” at address FFFFFFFF appears in link map 

SDSsq03798 

Encoding of MPYF SUBF changed from v4.7 

SDSsq03892 

preprocessing does not work correctly for conditional compilations 

SDSsq03896 

asm(“ ”) statement with circular addressing not compiled corrected by 

C compiler 

SDSsq03909 

When converting to ascii-hex format, sometimes places entry point in 
output file 
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Bugs 

Description 

SDSsq03911 

Error when compiling code with #line preprocessor command 

SDSsq04011 

enhancement request - 40bit precision in register variable calls 

SDSsq04090 

v.5.00 ASM30 generates an INDIRECT ADDRESS REQUIRED error 
that v.4.70 does not. 

SDSsq04165 

Differences from V4.70 to V5.00 

SDSsq04167 

Inline memcpy being generated in c_intxx()’s 

SDSsq04220 

Optimizer ignores -onx from shell command line and -z from opt30 
command line. 

SDSsq04347 

The #pragma CODE_SECTION doesn’t work 
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Index 


-a linker option, 2 


-aa compiler option, |2-23 


2 - 24 ] 

tion,|2-23 


abort function, 5-22 


abs function, 5-22 


as intrinsic, 2-54 


absolute value, 
ac30 


5-22 5-36 


2-57 


acos function, |5-22 
-ad compiler option, |2-23| 
add_device function , |5-23| 
-al compiler optio n, |2-23| 
aliased variables, |2-20 


aliasing, |2-42 


alternate directories for include files, 2-33 


ANSI C, 

3-1-3-25, 5-64 

5-66 

ansi_fto 

, 2-54 



arc sine. 


5-25 


5-27 


arc tangent, 
archive library, [2^68 


archiver, 1-3 


-as compiler option, 2-23 


ASCII conversion functions, 


5-28 


asctime function, 5-25 5-34 


asin function, 5-25 


options, 


2-23 


assembler options, |2-23 


assembly language and C source statements, 2-49 


assembly language modules, |4-22 


assert function, |5-26 
assert.h header, 5-4||5-14 


atan function, 5-27 


atan2 function, 5-27 


atexit function, 5-271 5-36 
atof function 


5-28 


atoi function, 
atol function, 

-au compiler option, |2-23 


5-28 


5-28 


autoinitializatio n, |2-69 
RAM model, 

ROM model, 


4-6 


4-37 


2-69 

4-37 

4-38 

2-69 

4-37] 

4-39 


-ax compiler option, |2-23 


4-39 


-ar linker option, 2-24 

-b interlist utility option, 

2-64 

ARO (FP), 4-4 

-b linker option, |2-24 


AR1 (SP),|4-4| 

base-10 logarithm, |5-47 

t 


big memory model, |2-20 
_BIGMQDEL |2-31| 
bit fields, |3-3||3-23 


block linker directive, using to force .bss into a 64K 


data page, |2-36 
bmalloc function, 5-29 


bmallocl 6 function 
bmalloc8 function 


boot.obi,|2-68||2-69 


5-29 


5-29 


.asm extension, 2-14 

2-62 

branch delay slot filling, 

3-21 

asm statement, 

2-41 

4-28 

broken-down time, 5-11 

5-34 5-52 

C language, 

3-17 


bsearch function, 

5-30 



assembler, 

1M. 

2-57 


.bss section, 

2-70 

4-3 




forcing into a 64K data page, 2-36 
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Index 


buffer 


define and associate function, 5-61 


specification function, |5-59 


BUFSIZE macro, 5-9 


-c compiler option, M2 

2-28 

2-67 

.c extension, 

2-4 

2-57 


C language, characteristics, |3-2| 

—c library build utility optio n, |6-2 
-c linker option, l- 24, 2-65| 2-66 2-69 


C source statements and assembly language, |2-49 
C_DIR environment variable, |2-33 
c int0,|2-69 


C_OPTION environment variable, 


C30, 

2^31 

CO 

O 

1 

2-31 

_C3x, 

2-31 

1 

o 

4^ 

O 

2-31 

1 

o 

-p^ 

X 

2^3? 


2-12 


2-28 


calendar time, 5-11 

5-34 

5-52 

5-76 

calloc function, 4-4 

5-31 

5-41 

5-51 


calloc16 function 
calloc8 function 


ceil function, 5-32 


5-31 


5-31 


cg30, 2-62 


character 

conversion functions, a number of characters, 


5-74 


read function, multiple characters, 5-38 


read functions, single character, 5-38 


character constants, 3-23 


character sets, 3-2 


character-t yping c onversion functions, |5-5||5-14 
isalnum, 5^5 
isalpha , |5-45| 
isascii, |5-45 
iscntrl, |5-45 
isdigit, |5-45 
isgraph, 5_45 
islower, 5-45 
isprint, 5-451 



isxdigit, 5-45 


toascii, 5-76 


tolower, 5-77 


toupper, |5-77 


2-69 


2-64 


.cinit section, 

.cl extension, 
clear EOF function 
clearerr function 


2-70 4-2, 4-38 


5-32 


5-32 


clist, 2-64 


CLK TCK macro, 5-11 5-33 


clock function, 5-33 


clock_t type,|5-11 


close file function, |5-37 
CLOSE I/O function 
code generator, 
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2-56 


options, |2-63 


2-62 


code-E error messages, 

2-16 

2-51 

code-F error messages, 

2-51 


code-1 error messages, 2-52 


code-W error messages, 2-51 


CODE SECTION pragma, 3-12 


compare strings, 


5-69 


compatibility, ! 3-2 j - j3-23 
compiler 


branch delay slot filling, |3-21 
description !^ +2-751 


error ha ndling , 2-51 
far calls, |3-20l 
intrinsics support, 
invoki ng th e , |2-3| 
limits, ! 3-24-t3-25| 
optimizer, 2-56 
options, 2-61 2-11 
overview, 2-56 


2-54 


-2-75 


running as sep arate passes! 2-5q-|2-64 


sections, 2-70 


compiling C code, |2-2 
concatenate strings, 5-63||5-68 


.const section, 3-18 


4-2 


conversions, 

C langua ge, |3-3 
cos function, 5-33 


cosh function, 5-34 
cosine, 


5-33 


constants, C language, 3-2 

3 ^ 115 ^ 


-cr linker option, ’-24, 2-66 |2-69 4-6 


ctime function, 5-34 


ctype.h header, 5-5 5-14 
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Index 


n 

ERANGE macro, 5-5 

Li 

errno.h header, 5-5 


-d compiler option, |2-12 
.data section, [4^3| 

data types, C language p-T^J 3-4 ~ |3-6| 
DATA_SECTION pragma, 13031 
DATE 


2-31 


daylight savings time, |5-11 
debugging optimized code, 


2-40 


2-19 


declarations, C language, |3-3 
default argument promotions, 
defining variables in assembly language, [4-25 
device 


adding, B-5 


functions, 5-23 


5-26 


diagnostic information, 
diagnosti c mess ages, 5-4 


assert, 5-26 


NDEBUG macro. SeeNDEBUG macro 


difftime function, 5-34 


div function, 5-35 


div t type, 5-10 


division, 3-3 


dspcl, 2-3 


dynamic memory allocation, 4-4 


error 


indicators functio n, |5-32 
mapping function, |5-53 


error handling, f2^5l| — 2-53 


using error options 
error message macros 


3-22 


2-53 


assert, 5-26 


5-14 


error mess ages 
code-E |2-5l| 
code-F, I 2 T 5 TT 



error options 
error reporting, |5-5 
errors treated as warnings 
escape seguences, 


3-2 


3-23 


exit function, 15-22115-27] 


2-52 


5-36 


exp function, 5-36 


exponential math function, 5-8 5-36 


expressions, 


3-3 


C language, 3-3 


external declarations, 3-22 


e com piler o ption, T4j 2-14 


ea, 2-14 


-eo, 2-14 


-e linker option, 2-24 


EDOM macro, 5-5 
entry points 


c into, 2-69 


for C code, 2-69 


reset vector, 2-69 


enumerator list, trailing comma, |3-23 
environment information function, 5-44 


environme nt var i able, |2-28 2-33 
C DIR, [ 2 ^ 32 !|2 33 
C O PTION , 12-28 
TMP, 


2-28 


5-9 


EOF macro, 

EPROM programmer, |1 -4 


-f com piler o ption, |2-4||2-15 


-fa, 2-15 


■fc, 2-15 


■fo, 2-15 


-f linker option, 2-24 


-fa file specifier, 2-15 


fabs function, 5-36 


as intrinsic, 2-54 


far calls, 3-20 


fastjtoi intrinsic, 2-54 


fast imult intrinsic, 2-54 


fastjnvf intrinsic, 2-54 


fatal errors, 2-5l[ 2-52 


-fc file specifier, 


2-15 


fclose function, |5-37| 


feof function, 5-37 


terror function, 


5-37 


fflush function, 5-37 
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fgetc function, |5-38 
fgetpos function, 


5-38 


fgets function, |5-38 
file 

removal function , |5-58l 
rename function, |5-58| 
FILE data type, |5-9| 


file extension, 2-14 


-ea option, 2-14 


-eo option, 2-14 


-f option, M5 


file specifier option s, |2-1 4 
-e option |2-1 4 


file.h header, |5-5 
FILE , 12-31 


filename, generate function, 


5-76 


filename extensions, 2-4 


filename specifications, 2-4 


FILENAMEJVIAX macro, 5-9 


flib.lib, 2-68 


float.h header, 5-6 


.float40 section, 3-6 


floating- point m ath functions, |5-8[|5-14||5-1 5 
acos 


5-22 


asin,b^25| 
atan. |5-27| 
atan 2, |5-2 7| 
ceil, 
cos, 
cosh , |5-34 
exp, |5-36F 
tabs, 5-36 
floor, [5X39 
5-39 


5-42 


Ide xp, |5-46 
log, |5-46| 
log 10 |5-47 
modf,|5-53| 
pow, 


5-54 


sinh |5-62 
sgrt ,|5-62 
tan, 5-75| 
tanh, |5-75 


floating-point remainder, 5-39 


floor function, 5-39 


flush I/O buffer function, 5-37 


fmod function, 5-39 


-fo file specifier option, 2-15 


fopen function, 5-39 


FOPEN MAX macro, 5-9 
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inline functions, 2-44 


input/output definitions, 5-5 


integer division, 5-35 


asm statement, 

4-28 

interlist utility, 2-49 

2-64 

options, 2-64 


using with optimizer, 2-40 


intermediate file, |2-57[|2-59| 
interrupt handling |T3Cl - |4-3l| 
INTERRUPT pragma, 13^61 


intrinsic oper ators, |2-45 


abs, |2-54 
ansi ftoi, 


tabs, 2-54 


2-54 


fast ftoi, 2-54 


fast imult, 2-54 


fast invf, 2-54 


frieee, 2-54 


labs, 2-54 


toieee, 2-54 


inverse tangent of y/x, |5-27 
invoking the 


C compiler, 2-3 


C compiler tools individually, 2-56 


library build utility, 6-2 


linker, |2-65 
optimizer, 
parser, 


code generat or, |2-62 
interlist utility. 12-49112-64 


2-60 


2-57 


5-45 


isalnum function, 
isalpha function, 5-45 


isascii function, 5-45 


iscntrl function, 5-45 


isdigit function, 5-45 


isgraph function, 5-45 


islower function, 5-45 


isprint function, |5-45 


ispunct function, |5-45 


isspace function, 5-45 


isupper function, [5^45 
isxdigit function, 5-45 
isxxx function, 5-5| 


5-45 


-k compiler option, 2-12 


—k library build utility option, 
K&R, |2-16| 

compatibility, [3^1- |3-25| 


-I library build utility option, 6-2 


I linker option. 2-25 2-66 |2-68 


Ltmpnam macro, |5^9 
labs function 


5-22 


as intrinsic, 2-54 


Idexp function, |5-46 
Idiv function 


5-35 


Idiv t type, |5-10 
libraries 


5-2 


library build utility, M-316-1; -6-6 


optional object library, |6^2| 
options, 
limits 


compiler, 3-2* -3-25 


floating-point type s 
integer types, |fT6 


— 3-25] 
:ypes,|5-6| 


limits.h header, 5-6 


line and file information, suppressing, 
#line directive, 


2-17 


LINE ,2-31 


2-34 


linker, 2-57 


invocation, 2-65 


Ink30 command, 

options _ 

-a, 

-a/-,g4| 


2-65 


-c o verrid e option, 2-6 7 
-cr. j?-24\ 

-h ,. 2-24 


Index-6 











































































































































































Index 


-heap, ]?-24 
-heap 1 6, \ 2-24 
-heap8 |2-24j 



-z enabling option, \ 2-66 
linker command file ] 2-714-2-71: 
linking C code ] 2-6 j - |-2-75| 


linking with the shell program, |2-66 


listing file, 2-34 


generating, [2^16 


lnk30, |2-65 
loader, 3-18 


2-66 


5-11 5-34 


local time. 


localtime function, 5-46 5-52 


log function, 5-46 


loglO function, 5-47 


long double data type, |3-5 
longjmp function, 


5-60 


low-level I/O functio ns, |5-5| 
LSEEK I/O function, |B-7| 


Itoa function, 5-47 


-m linker option, |2-25 


-ma compiler option, |2-20 


macro definitions, 2-31-2-32 


macro expansions 
macros 

SEEKCUR 
SEEK END 


2-3l- |2-32 


SEEK SET, |5-10 
stden, 


5-10 


stdin, 
stdout, 5-10 


5-10 


5-10 


5-10 


5-48 


malloc function, |4-4 5-41 5-48 5-51 
malloc16 function 
malloc8 function 
math.h header. 


5-48 


5-8||5-14||5T5 


-mb compiler option, 2-20| 


-me compiler option, 2-20 


memchr function, 5-49 
mememp function 
memepy function, 


5-49 


5-49 


5-50 


memmove function, 
memory m anage ment functions 
bmallo c,|5-29 
callo c, 15-31 
free, 15-41 1 


mallo c, 15-48 
minit, 5-51 
realloc, 5-571 


memory model | 4-$ -|4-6 

dynamic memory allocation, |4-4 


RAM model, 

ROM model, 
sectio ns, |4-2 

stack, |4-4| ~ _ 

memory pool, 5-29 |5-48 
reserved space, 4-3 
MEMORY SIZE, |5-10| 
MEMORY SIZE constant, 


4-4 


memset function, 5-50 


-mf compiler option, 2-21 


-mi compiler option, |2-21 
minit function, 5_-51 
minitl 6 function, 


minit8 function, 5-51 


5-51 


mk30, 6-2 


mktime function, 5-52 


-ml compiler option, |2-21 
-mm compiler option, |2^21 
-mn compiler option, |2-22 
modf function 


5-53 


modular programming, 2-65 


-mp compiler option, 2-22 


-mr compiler option, 2-22 
-ms compiler option 
-mt compiler option, |2-22 
-mtc compiler option 
multibyte characters, 13-2 


2-22 


Index-7 














































































































































































































Index 


-n compiler option, 2-12 


-n linker option, |2-25 


natural logarithm, 5-46 


NDEBUG macro, |5-4||5-26 
non-local jumps 


NULL macro, 5-9 


5-60 


.o extension 
-o linker option 
.obj extension, 
object libraries, |2-71 


■EL 

:ionjL2E 

)n,[2U4 _ 

es,|2^71 


25 2-66 


offsetof macro, 5-9 


-oi compiler option, 2-26 


-oi optimizer option, 2-26 


-ol compiler option, |2-26 
-oi optimizer option, |2-26| 
-olO compiler option, |2-26 
-oil compiler option, |2-26 


-o!2 compiler option, |2-26 


-oN optimizer option, 2-27| 


-on optimizer option, |2-26 
-oNO compiler option, p-27 
-oNI compiler option, g^27 
-oN2 compiler option , |2-27 
-op optimizer option, 2-27 
-opO compiler option, 1^27 
-opl compiler option, |2-27 
-op2 compiler option, |2-27 


open file function, [5-39 |5-41 
OPEN I/O function, |B-8 


.opt extension, 2-60 


opt30, 2-60 


optimization 

general, 


A- 


A-1 


- |A-1 5 


algebraic reordering, A-£ 


alias disambiguation, A^S 
branch optimizations, A-12 


common subexp ress ion elimination, \A-10 
constant folding, 


A-£ 


control-flow simpli ficatio n, 
copy propagation, A-1C 


A-12 


inline function expansion, A-15 1 
loop induction variable opti mizati ons, \A-12\ 
loop invarian t code motion , \ aT 5 
loop rotation, \A-1f\ 

redundant assign ment el imination, A-10 \ 


strength reduction \A-12\ 


symbolic simplification, \A 


information file, options, 2-27 


library functions, optio ns, |2-26 
TMS320C30-specific, A-1 


autoi ncre ment addressing, \A-4 
calls, \A-dj 
cost-based register allocation, \A 


delayed branc hes, \A-t 
repeat blocks, \ A- 


returns, A-t 


invoking, 2-60 


options, 2-60 

2-61 

parser output, 

2-59 


special considerations, 2-41 


using with interlist utility, |2-40 
options 


2-J-2-29 


assembler, 2-23 


code generat or, |2-63 
conventions, 2-5 


file specifiers, 2-14 


general, 2-12 


optimiz er, |2-26| 
parser, |2-16||2-58 


runtime-model, 2-20 


summary table, 2-6 


type-checking, 2-19 


-os compiler option, |2-2~7]|2-50 


-p? compiler option, |2-18||2-34 
parser, |2-56||2-57 


options, |2-16l|2-57 


parsing in two passes, 


2-58 


2-59 


-pe compiler option, j2-16 

2-51 2-52 

perror function, 5-53 


-pf parser option, 2-16 


-pk compiler option, 2-16 

3-22 3-23 


-pi compiler option , |2-16 
-pm parser option, 2-17 


-pn compiler option, 2-17 
-po compiler option, 2-17 


2-34 


2-34 


2-34 


Index-8 




















































































































































































































Index 


-po option, £-59 


pointer combinations, 3-22 


position file indicator function, 5-59 


pow function, |5-54 
power, 


5-54 


pragma, 3-3 


CODE_SECTION, ES, 3-12 


3-13 


3-14 


DATA_SECTION 
FUNC_CANNOT_INLINE 
FUNC_EXT_CALLED 
FUNC IS PURE, |3-14 
FUNCISSYSTEM 
FUNC_NEVER_RETURNS, 
FUNC_NO_GLOBAL_ASG, 
FUNC NO I ND A SG, |3-16 
INTERRUPT, 


3-13 


3-15 


3-16 


3-15 


3-15 


predefined name sj2-: -|2-32 
J3IGMODEL [?3" 
_REGPARM 
C30, 


C31, 
C32, 
C3x, 
C40, 
C44, 
C4x, 


2-31 


2-31 


2-31 


2-31 


2-31 


2-31 


2-31 


DATE 

FILE 



2-31 


2-31 


2-31 


INLINE, 2-31 2-46 


LINE, 2-31 


STDC, 2-31 


TIME, 2-31 


TMS320C30, 

2-31 

TMS320C31, 

2-31 

TMS320C32, 

2-31 

TMS320C3X, 

2-31 

TMS320C40, 

2-31 

TMS320C44, 

2-31 

TMS320C4X, 

2-31 


preinitialized variables, |3-1 8 
preprocess only, |2-17| 


preprocessed listing file 
2X|J-£j34 


preprocessor, 


environm ent va riable 
listing file 


2-16 


2-34 


2-33 


predefining name,|2-12 


symbols, 2-31 


preprocessor di rect ives, |2-30 
C language, 3-3 


trailing tokens, 3-23 


printf function, 5-54 


program termi nation functions 


abort (exit), 5-22 


atexit, 5-27 
exit 


5-36 


prototype listing file,|2-16 
pseudorandom, 5-57 
ptrdiffj type, |3-2[ |5 -9 
putc fu notion, |5^54 
putchar function, 


puts function, |5-55 


5-55 


-pw option, 2-52 


-g compiler option, £-3||2-13 


-q interlist utility option, 2-64 


—q library build utility option, fT-2 
-q linker option, £-25 


-qq compiler option, 2-13 


qsort function, 5-56 


-r interlist utility option, 2-64 


-r linker option, 2-25 


RAM model of autoinitialization, 4-6 


RAM model of initialization, 2-69 


rand function, 5-57 


RAN DM AX macro, |5-10 
read 

character functions 

multiple characters, 5-38[ 


next character function, 5-43 5-44 


single character, \5-3t 
stream functions 
from standard input, 


from s tring to arra y, 5-4C 


string, 5-42 


read function, 5-44 


5-6c 


5-59 


READ I/O function, 


realloc function, 4-4 


5-58 


realloc16 function, 


realloc8 function, 5-58 


5-41 


recoverable errors, 2-51 


5-51 


5-57 


5-61 


Index-9 



































































































































































































Index 


register conventions 4-1' - H-14 
register variables, |4-12 


register storage class, |3-3 
register variables, |4-12 
C language 
REGPARM 


3-10 


2-31 


5-58 


5-58 


remove function, 
rename function, 
RENAME I/O function 
rewind function, 


B-9 


5-59 


ROM model of autoinitialization, |4-6 
ROM model of initialization 
rts.lib 


2-69 


2-68, 2-69 5-1 


2-35 


2-66 


2-35 


rts.src, |5JJ |5^[ |5-10[ |6-1 
rts30.lib, 
rts30g.lib, 
rts30gr.lib 
rts30r.lib 


2-35 


2-35 


rts40.lib, 2-35 2-66 


rts40g.lib, 2-35 


rts40gr.lib, |2-35 
rts40r.lib, 12-35 


runtime environment 4-'-4-40 


defining variables in ass embly l angua ge, |4-25 
function call conventions 


TTI1-F2T 

i, |4-28| 


inline assembly language, 
interfacing C with assembly la nguage l 4-2j - |4-29 
interrupt handling 
memory model 


4-3C-4-31 


dynamic me mory allocation, 
RAM model, 

ROM mo del, \4-(\ 
sections, \4-2 


4-4 


stack, 4-4 



-s linker option 
scant function, 5-59 
searches , |5-30| 
sectionsjTIl 
.bss,|7 
■cinit, 14-38 
.data,H^ 

.stackj4~3 
.sys mem 4-3 
.text, 

SEEK_CUR macro, 
SEEK_END macro, 
SEEK_SET macro, |5-10 
set file-position fu nction s 
fseek function, 


5-42 


5-59 


fsetpos func tion, |5-43 
setbuf function _ 
setjmp function, 
setvbuf function 
shell program 


5-60 


5-61 


2-3- 2-4 


-i option, |2-33| 

C OPTION environment variable, 


enabling linking, 2-13 


2-28 


keeping the assembly language file, 2-12 


overview, 2-2 


suppressing the linking option, 
shift, 


2-12 


3-3 


sinh function 
size_t type, |3-2 


5-62 


5-9 


small memory model, [2^2o| 
software development toolsl 1-|- |1-4| 
sorts, 


5-56 


source file extensions 
assembler files 
C source files 


2-15 


2-15 


runtime-model options, 2-20 


3 4-i-_fTT4 

object files, 2-15 

SP register, ^ 4 ] 

4-36-4-40 

specifying filenames, 2-4 2-14 


runtime-support libraries, ?-35 |2-66| |2-68l|fH 
runtime-support fu nctio n s! 5-j - |5-21 
summary table ] 5-1$ 


-21 


runtime-support libraries, |5-2| 


sprintf function 
sqrt function 
square root, 


5-62 


5-62 


5-62 


srand function, 


5-57 


-ss compiler option, M3j|2-49||2-50 


sscanf function, 5-63 


stack, 4-3 


-s compiler option, ^-1 3 2-50 


reserved space, 4-3 


-stack linker option, 2-25 


Index-10 


































































































































































































Index 


stack management, |fM 


stack pointer, 4-4 


.stack section, 4-3 


STACKSIZE constant, 4-4 


static variables, 3-18 


reserved space, |fF3 
stdarg.h header, 5-8 |5-15 

_STDC_, |2-31 

stddef.h header, [5^9 
stden macro, 5-10 
stdin macro, 5-10 
stdio.h heade r, 15-15 
described, 5^9 
stdlib.h header, 5-10||5-17 
stdout macro, [5^10 
store object function, 5-38 
strcat function, [5^63 
strchr function, 5-64 
strcmp function, [5^64 
strcoll function, 5-64 
strcpy function, [5^65 
strcspn function, [5^65 
strerror function, 5-66 
strftime function, 5-66 
string copy, |5-70 
string functi ons, 5-11 5-19 
memchr, 5-49 


5-49 

5-491 


memcmp, 
memcpy, 
memmo ve,|5-50 
mems et,|5-50 
strcat, 5-63 
strchr, 5-64 
strcmp TlfT64 
strcoll, 5^34 
strcpy, ^65 
strcspn, 5-651 
strerror, 5-66| 
strlen, |5^67| 
strncat l5^68| 
strncmp Tl5-69| 
strncpy, 15^701 
strpbrk,|5-71| 


strtok, 5-74 


string.h header, 5-11 
strlen function, 5-67 
strncat function. 


5-19 


5-68 


strncmp function, |5-69 


strncpy function, 5-70 


strpbrk function, |5-71 
strrchr function, 
strspn function, 


5-71 


5-72 


strstr function, |5-72 
strtod function, 5-73 


strtok function, [5^74 
strtol function, 15-73 


strtoul function, 5-73 


structure members 
strxfrm function 


5-74 


STYP CPY flag, |2-70 
suppress 


all output except er ror me ssages, |2-1 3 
banner information, 2-13 
line and file information, 
linker option, 


2-12 


2-17 


suppressing warning messages, 
.switch section 


2-52 


2-7C -2-75 


symbolic debugging, 2-64 


symbolic debugging directives, 2-12 


.sysmem section, 4-3 


system constraints 
MEMORY_SIZE,|4-4 
STACK SIZE, pP4 


system initialization 4-36-4-40 


autoinitialization, ]4K37 


system stack, 4-3 



tan function, 


5-75 


tangent, 5-75 


tanh function, |5-75 
target processor, 


2-13 


temporary file creation function, 5-76 


tentative definition, 3-23 
test EOF function 
test error function 
.text section, 


5-37| 


2-70 


5-37 


4-2 


Index-11 






























































































































































Index 


-tf compiler option, |2-19| 

The C Programming Language l 3-1 ~ |3-25| 
time, |5-25 
time function, |5-76 
time functions, 15-11 



time, [5^76 
time.h head er, |5-1 1 

_TIME_ , |2-3lT 

time_t type, |5-1l| 
tm structure, [5^lT| 
tm type. See broken-down time 


TMP environment variable, 2-28 


overriding, 2-29 


TMP MAX macro, 


5-9 


tmpfile function, |5-76 
tmpnam function, 5-76 


_TMS320C30, 2-31 
TMS320C31, E-31 


TMS320C32, |2X3T 


TMS320C3x,[2X31 


TMS320C3x/C4x C l anguage, co mpatibility with 
ANSI C language [3^|-|3^23] 

TMS320C40, 


2-31 


2-31 


_TMS320C44, 
TMS320C4x, 
toascii function, 
toieee intrinsic, 2-54 


2-31 


5-76 


tokens, 5-74 


tolower function, 5-77 


toupper function, 5-77 


-tp compiler option, [2-19 


trailing comma, enumerator list, 3-23 


trailing tokens, preprocessor directives, 3-23 


translation phases, 2-34 


trigonometric math function, 


5-8 


trigraph expansion, 2-18 


trigraph sequences, 2-34 


type-checking, pointer combinations, |2-1 9 


type-c hecki ng options, |2M9 


-tf, 2-19 


-tp, 2-19 


-u compiler option, 2-13 


-u library build utility option, 


-u linker option, 2-25 


ungetc function, [5^77 


uninitialized sections, 2-70 4-3 


.bss, 4-3 


UNLINK I/O function, B-10 


-v compiler option, |2-13 
—v library build utility option, H|| 
-vO linker option, |2-25 


va_arg function, |5-78 
va_end function, 
va start function 


5-78 


5-78 


variable argument functions and macros, 5-8 5-15 


variable-argument function, 5-78 


variable-ar gume nt functions and macros 


va arg, |5-78 
va end,|5-78 


va start, 5-78 


vfprintf function, |5-79 
volatile 


2-41 


vprintf function, |5-79 
vsprintf function, 5-79 


-w linker option, |2-25 


warning messa ges, |2-51 
suppressing, [2^52| 


warnings messages, 


3-22 


wildcard, 2-4 


write block of data function, |5-43 
write functions 


5-40 


fprintf , |5-40 
fputc, 
fputs, 


5-40 


Index-12 





























































































































































Index 


printf, 5-54 


putc, 5-54 


putchar, 5-55 


puts, 5-55 


sprintf, |5-62 
ungetc, 
vfprintf, 


5-77 


vprintf, 5-79 


5-79 


vsprintf, 5-79 


WRITE I/O function, B-10 


-x compiler option, 2-18 
-x inlining option, 2-18 


-x linker option, 2-25 


-z code generator option, 2-63 


-z compiler o ption ^3] £-1 3 2-28||2-65||2-66 
overriding, 2-28 


Index-13 
















































